# keycloak_client_rolescope – Allows administration of Keycloak client roles scope to restrict the usage of certain roles to a other specific client applications — Keycloak Ansible Collection documentation

# keycloak_client_rolescope – Allows administration of Keycloak client roles scope to restrict the usage of certain roles to a other specific client applications

Note

This module is part of the middleware_automation.keycloak collection.

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

To install it, use: `ansible-galaxy collection install middleware_automation.keycloak`.

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

New in middleware_automation.keycloak 3.0.0

## Synopsis

- This module allows you to add or remove Keycloak roles from clients scope 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, 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.

- Client `target_client_id` must have `full_scope_allowed` set to `false`.

- 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.

## Parameters

Parameter | Comments
--- | ---
auth_client_id string | OpenID Connect client_id to authenticate to the API with. Default: `"admin-cli"`
auth_client_secret string | Client Secret to use in conjunction with auth_client_id (if required).
auth_keycloak_url aliases: url string / required | URL to the Keycloak instance.
auth_password aliases: password string | Password to authenticate for API access with.
auth_realm string | Keycloak realm name to authenticate to for API access.
auth_username aliases: username string | Username to authenticate for API access with.
connection_timeout integer | Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: `10`
http_agent string | Configures the HTTP User-Agent header. Default: `"Ansible"`
realm string | The Keycloak realm under which clients resides. Default: `"master"`
refresh_token string | Authentication refresh token for Keycloak API.
role_names list / elements=string / required | Names of roles to manipulate. If `role_owner_client_id` is present, all roles must be under this client. If `role_owner_client_id` is absent, all roles must be under the realm.
role_owner_client_id string | If the `role_names` are client role, the client ID under which it resides. If this parameter is absent, the roles are considered a realm role.

state

string

State of the role mapping.

On `present`, all roles in `role_names` are mapped if not exist yet.

On `absent`, all roles mapping in `role_names` are removed if it exists.

Choices:

- `"present"` ← (default)

- `"absent"`

target_client_id string / required | Roles provided in `role_names` while be added to this client scope.
token string | Authentication token for Keycloak API.

validate_certs

boolean

Verify TLS certificates (do not disable this in production).

Choices:

- `false`

- `true` ← (default)

## Attributes

Attribute | Support | Description
--- | --- | ---
action_group | Action group: middleware_automation.keycloak.keycloak added in middleware_automation.keycloak 3.0.0 | Use `group/middleware_automation.keycloak.keycloak` in `module_defaults` to set defaults for this module.
check_mode | Support: full | Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode | Support: full | Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

## Examples

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

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

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

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Description
--- | ---

end_state

list / elements=dictionary

Representation of role role scope after module execution.

Returned: on success

Sample: `[{"clientRole": false, "composite": false, "containerId": "MyCustomRealm", "id": "47293104-59a6-46f0-b460-2e9e3c9c424c", "name": "backend-role-admin"}, {"clientRole": false, "composite": false, "containerId": "MyCustomRealm", "id": "39c62a6d-542c-4715-92d2-41021eb33967", "name": "backend-role-user"}]`

msg string | Message as to what action was taken. Returned: always Sample: `"Client role scope for frontend-client-public has been updated"`

### Authors

- Andre Desrosiers (@desand01)