.. Document meta

:orphan:

.. |antsibull-internal-nbsp| unicode:: 0xA0
    :trim:

.. meta::
  :antsibull-docs: 2.24.0

.. Anchors

.. _ansible_collections.middleware_automation.keycloak.keycloak_client_scope_rolemappings_module:

.. Anchors: short name for ansible.builtin

.. Title

keycloak_client_scope_rolemappings -- Allows administration of Keycloak client scope scope mappings to restrict the usage of certain roles to specific client scopes
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. Collection note

.. note::
    This module is part of the `middleware_automation.keycloak collection <https://galaxy.ansible.com/ui/repo/published/middleware_automation/keycloak/>`_.

    It is not included in ``ansible-core``.
    To check whether it is installed, run :code:`ansible-galaxy collection list`.

    To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`.

    To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_client_scope_rolemappings`.

.. version_added

.. rst-class:: ansible-version-added

New in middleware\_automation.keycloak 3.0.0

.. contents::
   :local:
   :depth: 1

.. Deprecated


Synopsis
--------

.. Description

- This module allows you to add or remove Keycloak roles from client scopes using the Keycloak REST API. It requires access to the REST API using OpenID Connect; the user connecting and the client being used must have the requisite access rights. In a default Keycloak installation, :literal:`admin\-cli` and an admin user would work, as would a separate client definition with the scope tailored to your needs and a user having the expected roles.
- Attributes are multi\-valued in the Keycloak API. All attributes are lists of individual values and are returned that way by this module. You may pass single values for attributes when calling the module, and this is translated into a list suitable for the API.


.. Aliases


.. Requirements






.. Options

Parameters
----------

.. raw:: html

  <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
  <thead>
  <tr class="row-odd">
    <th class="head"><p>Parameter</p></th>
    <th class="head"><p>Comments</p></th>
  </tr>
  </thead>
  <tbody>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-auth_client_id"></div>
      <p class="ansible-option-title"><strong>auth_client_id</strong></p>
      <a class="ansibleOptionLink" href="#parameter-auth_client_id" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>OpenID Connect <em>client_id</em> to authenticate to the API with.</p>
      <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;admin-cli&#34;</code></p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-auth_client_secret"></div>
      <p class="ansible-option-title"><strong>auth_client_secret</strong></p>
      <a class="ansibleOptionLink" href="#parameter-auth_client_secret" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Client Secret to use in conjunction with <em>auth_client_id</em> (if required).</p>
    </div></td>
  </tr>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-auth_keycloak_url"></div>
      <div class="ansibleOptionAnchor" id="parameter-url"></div>
      <p class="ansible-option-title"><strong>auth_keycloak_url</strong></p>
      <a class="ansibleOptionLink" href="#parameter-auth_keycloak_url" title="Permalink to this option"></a>
      <p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: url</span></p>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
        / <span class="ansible-option-required">required</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>URL to the Keycloak instance.</p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-auth_password"></div>
      <div class="ansibleOptionAnchor" id="parameter-password"></div>
      <p class="ansible-option-title"><strong>auth_password</strong></p>
      <a class="ansibleOptionLink" href="#parameter-auth_password" title="Permalink to this option"></a>
      <p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: password</span></p>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Password to authenticate for API access with.</p>
    </div></td>
  </tr>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-auth_realm"></div>
      <p class="ansible-option-title"><strong>auth_realm</strong></p>
      <a class="ansibleOptionLink" href="#parameter-auth_realm" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Keycloak realm name to authenticate to for API access.</p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-auth_username"></div>
      <div class="ansibleOptionAnchor" id="parameter-username"></div>
      <p class="ansible-option-title"><strong>auth_username</strong></p>
      <a class="ansibleOptionLink" href="#parameter-auth_username" title="Permalink to this option"></a>
      <p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: username</span></p>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Username to authenticate for API access with.</p>
    </div></td>
  </tr>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-client_id"></div>
      <p class="ansible-option-title"><strong>client_id</strong></p>
      <a class="ansibleOptionLink" href="#parameter-client_id" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>If the <code class="ansible-option literal notranslate"><strong><a class="reference internal" href="#parameter-role_names"><span class="std std-ref"><span class="pre">role_names</span></span></a></strong></code> are client roles, the client ID under which it resides.</p>
      <p>If this parameter is absent, the roles are considered realm roles.</p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-client_scope_id"></div>
      <p class="ansible-option-title"><strong>client_scope_id</strong></p>
      <a class="ansibleOptionLink" href="#parameter-client_scope_id" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
        / <span class="ansible-option-required">required</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Roles provided in <code class="ansible-option literal notranslate"><strong><a class="reference internal" href="#parameter-role_names"><span class="std std-ref"><span class="pre">role_names</span></span></a></strong></code> will be added to this client scope.</p>
    </div></td>
  </tr>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-connection_timeout"></div>
      <p class="ansible-option-title"><strong>connection_timeout</strong></p>
      <a class="ansibleOptionLink" href="#parameter-connection_timeout" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">integer</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Controls the HTTP connections timeout period (in seconds) to Keycloak API.</p>
      <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">10</code></p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-http_agent"></div>
      <p class="ansible-option-title"><strong>http_agent</strong></p>
      <a class="ansibleOptionLink" href="#parameter-http_agent" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Configures the HTTP User-Agent header.</p>
      <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;Ansible&#34;</code></p>
    </div></td>
  </tr>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-realm"></div>
      <p class="ansible-option-title"><strong>realm</strong></p>
      <a class="ansibleOptionLink" href="#parameter-realm" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>The Keycloak realm under which clients resides.</p>
      <p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;master&#34;</code></p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-refresh_token"></div>
      <p class="ansible-option-title"><strong>refresh_token</strong></p>
      <a class="ansibleOptionLink" href="#parameter-refresh_token" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Authentication refresh token for Keycloak API.</p>
    </div></td>
  </tr>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-role_names"></div>
      <p class="ansible-option-title"><strong>role_names</strong></p>
      <a class="ansibleOptionLink" href="#parameter-role_names" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">list</span>
        / <span class="ansible-option-elements">elements=string</span>
        / <span class="ansible-option-required">required</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Names of roles to add.</p>
      <p>If <code class="ansible-option literal notranslate"><strong><a class="reference internal" href="#parameter-client_id"><span class="std std-ref"><span class="pre">client_id</span></span></a></strong></code> is present, all roles must be under this client.</p>
      <p>If <code class="ansible-option literal notranslate"><strong><a class="reference internal" href="#parameter-client_id"><span class="std std-ref"><span class="pre">client_id</span></span></a></strong></code> is absent, all roles must be under the realm.</p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-state"></div>
      <p class="ansible-option-title"><strong>state</strong></p>
      <a class="ansibleOptionLink" href="#parameter-state" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>State of the role mapping.</p>
      <p>On <code class="ansible-value literal notranslate">present</code>, all roles in <code class="ansible-option literal notranslate"><strong><a class="reference internal" href="#parameter-role_names"><span class="std std-ref"><span class="pre">role_names</span></span></a></strong></code> are mapped if not exist yet.</p>
      <p>On <code class="ansible-value literal notranslate">absent</code>, all roles mapping in <code class="ansible-option literal notranslate"><strong><a class="reference internal" href="#parameter-role_names"><span class="std std-ref"><span class="pre">role_names</span></span></a></strong></code> are removed if they exist.</p>
      <p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
      <ul class="simple">
        <li><p><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>&#34;present&#34;</strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;absent&#34;</code></p></li>
      </ul>

    </div></td>
  </tr>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-token"></div>
      <p class="ansible-option-title"><strong>token</strong></p>
      <a class="ansibleOptionLink" href="#parameter-token" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Authentication token for Keycloak API.</p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-validate_certs"></div>
      <p class="ansible-option-title"><strong>validate_certs</strong></p>
      <a class="ansibleOptionLink" href="#parameter-validate_certs" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">boolean</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Verify TLS certificates (do not disable this in production).</p>
      <p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
      <ul class="simple">
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">false</code></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>true</strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
      </ul>

    </div></td>
  </tr>
  </tbody>
  </table>



.. Attributes


Attributes
----------

.. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10}

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1
  :class: longtable ansible-option-table

  * - Attribute
    - Support
    - Description

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="attribute-action_group"></div>

      .. _ansible_collections.middleware_automation.keycloak.keycloak_client_scope_rolemappings_module__attribute-action_group:

      .. rst-class:: ansible-option-title

      **action_group**

      .. raw:: html

        <a class="ansibleOptionLink" href="#attribute-action_group" title="Permalink to this attribute"></a>

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      :ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak`

      :ansible-option-versionadded:`added in middleware\_automation.keycloak 3.0.0`


      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module.


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="attribute-check_mode"></div>

      .. _ansible_collections.middleware_automation.keycloak.keycloak_client_scope_rolemappings_module__attribute-check_mode:

      .. rst-class:: ansible-option-title

      **check_mode**

      .. raw:: html

        <a class="ansibleOptionLink" href="#attribute-check_mode" title="Permalink to this attribute"></a>

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full`


      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Can run in :literal:`check\_mode` and return changed status prediction without modifying target.


      .. raw:: html

        </div>


  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="attribute-diff_mode"></div>

      .. _ansible_collections.middleware_automation.keycloak.keycloak_client_scope_rolemappings_module__attribute-diff_mode:

      .. rst-class:: ansible-option-title

      **diff_mode**

      .. raw:: html

        <a class="ansibleOptionLink" href="#attribute-diff_mode" title="Permalink to this attribute"></a>

      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      :ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full`


      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode.


      .. raw:: html

        </div>



.. Notes


.. Seealso


.. Examples

Examples
--------

.. code-block:: yaml+jinja

    - name: Add roles to client scope
      middleware_automation.keycloak.keycloak_client_scope_rolemappings:
        auth_keycloak_url: https://auth.example.com
        auth_realm: master
        auth_username: USERNAME
        auth_password: PASSWORD
        realm: MyCustomRealm
        client_id: frontend-client-public
        client_scope_id: frontend-client-scope
        role_names:
          - backend-role-admin
          - backend-role-user

    - name: Remove roles from client scope
      middleware_automation.keycloak.keycloak_client_scope_rolemappings:
        auth_keycloak_url: https://auth.example.com
        auth_realm: master
        auth_username: USERNAME
        auth_password: PASSWORD
        realm: MyCustomRealm
        client_id: frontend-client-public
        client_scope_id: frontend-client-scope
        role_names:
          - backend-role-admin
        state: absent

    - name: Add realm roles to client scope
      middleware_automation.keycloak.keycloak_client_scope_rolemappings:
        auth_keycloak_url: https://auth.example.com
        auth_realm: master
        auth_username: USERNAME
        auth_password: PASSWORD
        realm: MyCustomRealm
        client_scope_id: frontend-client-scope
        role_names:
          - realm-role-admin
          - realm-role-user



.. Facts


.. Return values

Return Values
-------------
Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this module:

.. raw:: html

  <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
  <thead>
  <tr class="row-odd">
    <th class="head"><p>Key</p></th>
    <th class="head"><p>Description</p></th>
  </tr>
  </thead>
  <tbody>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="return-end_state"></div>
      <p class="ansible-option-title"><strong>end_state</strong></p>
      <a class="ansibleOptionLink" href="#return-end_state" title="Permalink to this return value"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">list</span>
        / <span class="ansible-option-elements">elements=dictionary</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>Representation of client scope scope mappings after module execution.</p>
      <p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> on success</p>
      <p class="ansible-option-line ansible-option-sample"><strong class="ansible-option-sample-bold">Sample:</strong> <code class="ansible-value literal notranslate ansible-option-sample">[{&#34;clientRole&#34;: false, &#34;composite&#34;: false, &#34;containerId&#34;: &#34;77f9bd4e-13a6-451e-9c72-ee6997299c1f&#34;, &#34;description&#34;: &#34;User role&#34;, &#34;id&#34;: &#34;9e155ef7-86f5-4def-b507-581ce7b87013&#34;, &#34;name&#34;: &#34;realm-role-user&#34;}, {&#34;clientRole&#34;: false, &#34;composite&#34;: false, &#34;containerId&#34;: &#34;77f9bd4e-13a6-451e-9c72-ee6997299c1f&#34;, &#34;description&#34;: &#34;Admin role&#34;, &#34;id&#34;: &#34;9e155ef7-86f5-4def-b507-581ce7b87013&#34;, &#34;name&#34;: &#34;realm-role-admin&#34;}]</code></p>
    </div></td>
  </tr>
  </tbody>
  </table>



..  Status (Presently only deprecated)


.. Authors

Authors
~~~~~~~

- Felix Grzelka (@felix-grzelka)


.. Extra links


.. Parsing errors