# keycloak_client_scope – Allows administration of Keycloak client scopes via Keycloak API — Keycloak Ansible Collection documentation

# keycloak_client_scope – Allows administration of Keycloak client scopes via Keycloak API

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

New in middleware_automation.keycloak 3.0.0

## Synopsis

- This module allows you to add, remove or modify Keycloak client scopes via the Keycloak REST API. It requires access to the REST API via 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.

- This module also supports managing protocol mappers within a client scope.

## Parameters

Parameter | Comments
--- | ---
attributes dictionary | A dict of key/value pairs to set as attributes for the client scope.
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`
description string | Description of the client scope. Default: `""`
http_agent string | Configures the HTTP User-Agent header. Default: `"Ansible"`
name string / required | Name of the client scope.

protocol

string

The protocol associated with the client scope.

Choices:

- `"openid-connect"` ← (default)

- `"saml"`

protocol_mappers list / elements=dictionary | A list of protocol mappers to associate with the client scope. Each mapper is a dict with the keys `name`, `protocol`, `protocolMapper`, and `config`. Default: `[]`
config dictionary / required | Configuration for the protocol mapper.
name string / required | Name of the protocol mapper.
protocol string | Protocol for the mapper. Default: `"openid-connect"`
protocolMapper aliases: protocol_mapper_type string / required | The mapper type (e.g. `oidc-usermodel-attribute-mapper`, `oidc-audience-mapper`).
realm string | The Keycloak realm under which this client scope resides. Default: `"master"`
refresh_token string | Authentication refresh token for Keycloak API.

state

string

State of the client scope.

On `present`, the client scope will be created if it does not yet exist, or updated with the parameters you provide.

On `absent`, the client scope will be removed if it exists.

Choices:

- `"present"` ← (default)

- `"absent"`

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 | 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: Create a client scope with protocol mappers
      middleware_automation.keycloak.keycloak_client_scope:
        auth_keycloak_url: http://localhost:8080
        auth_realm: master
        auth_username: admin
        auth_password: password
        realm: TestRealm
        name: my-client-scope
        description: "A custom client scope"
        protocol: openid-connect
        protocol_mappers:
          - name: email
            protocol: openid-connect
            protocolMapper: oidc-usermodel-attribute-mapper
            config:
              user.attribute: email
              claim.name: email
              jsonType.label: String
              id.token.claim: "true"
              access.token.claim: "true"
              userinfo.token.claim: "true"
        state: present
      delegate_to: localhost

    - name: Create a client scope using token authentication
      middleware_automation.keycloak.keycloak_client_scope:
        auth_keycloak_url: http://localhost:8080
        token: MY_TOKEN
        realm: TestRealm
        name: my-scope
        state: present
      delegate_to: localhost

    - name: Delete a client scope
      middleware_automation.keycloak.keycloak_client_scope:
        auth_keycloak_url: http://localhost:8080
        auth_realm: master
        auth_username: admin
        auth_password: password
        realm: TestRealm
        name: my-client-scope
        state: absent
      delegate_to: localhost

## Return Values

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

Key | Description
--- | ---
end_state dictionary | Representation of the client scope after module execution. Returned: on success Sample: `{"description": "A custom scope", "id": "uuid-here", "name": "my-scope", "protocol": "openid-connect"}`
msg string | Message as to what action was taken. Returned: always Sample: `"Client scope my-scope has been created"`

### Authors

- Paulo Menon (@paulomenon)