keycloak_client - Allows administration of Keycloak clients via Keycloak API

New in version 2.5.

Synopsis

Parameters

Parameter Choices/Defaults Comments
admin_url
URL to the admin interface of the client This is 'adminUrl' in the Keycloak REST API.

aliases: adminUrl
attributes
A dict of further attributes for this client. This can contain various configuration settings; an example is given in the examples section. While an exhaustive list of permissible options is not available; possible options as of Keycloak 3.4 are listed below. The Keycloak API does not validate whether a given option is appropriate for the protocol used; if specified anyway, Keycloak will simply not use it.
saml.signing.certificate
SAML signing key certificate, base64-encoded.
saml.server.signature.keyinfo.ext
For SAML clients, boolean specifying whether REDIRECT signing key lookup should be optimized through inclusion of the signing key id in the SAML Extensions element.
saml.authnstatement
For SAML clients, boolean specifying whether or not a statement containing method and timestamp should be included in the login response.
saml_force_name_id_format
For SAML clients, Boolean specifying whether to ignore requested NameID subject format and using the configured one instead.
jwks.url
For OpenID-Connect clients, URL where client keys in JWK are stored.
saml_single_logout_service_url_redirect
SAML redirect binding url for the client's single logout service.
saml.signing.private.key
SAML signing key private key, base64-encoded.
saml.force.post.binding
For SAML clients, boolean specifying whether always to use POST binding for responses.
saml.client.signature
For SAML clients, boolean specifying whether a client signature is required and validated.
saml.server.signature
Boolean specifying whether SAML documents should be signed by the realm.
jwt.credential.certificate
For OpenID-Connect clients, client certificate for validating JWT issued by client and signed by its key, base64-encoded.
saml_name_id_format
For SAML clients, the NameID format to use (one of username, email, transient, or persistent)
user.info.response.signature.alg
For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of RS256 or unsigned.
request.object.signature.alg
For OpenID-Connect clients, JWA algorithm which the client needs to use when sending OIDC request object. One of any, none, RS256.
saml_assertion_consumer_url_post
SAML POST Binding URL for the client's assertion consumer service (login responses).
saml.encrypt
Boolean specifying whether SAML assertions should be encrypted with the client's public key.
saml.signature.algorithm
Signature algorithm used to sign SAML documents. One of RSA_SHA256, RSA_SHA1, RSA_SHA512, or DSA_SHA1.
saml_signature_canonicalization_method
SAML signature canonicalization method. This is one of four values, namely http://www.w3.org/2001/10/xml-exc-c14n# for EXCLUSIVE, http://www.w3.org/2001/10/xml-exc-c14n#WithComments for EXCLUSIVE_WITH_COMMENTS, http://www.w3.org/TR/2001/REC-xml-c14n-20010315 for INCLUSIVE, and http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments for INCLUSIVE_WITH_COMMENTS.
saml.onetimeuse.condition
For SAML clients, boolean specifying whether a OneTimeUse condition should be included in login responses.
saml_single_logout_service_url_post
SAML POST binding url for the client's single logout service.
saml_assertion_consumer_url_redirect
SAML Redirect Binding URL for the client's assertion consumer service (login responses).
use.jwks.url
For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to obtain client public keys.
auth_client_id
required
 Default:
admin-cli
OpenID Connect client_id to authenticate to the API with.
auth_client_secret
Client Secret to use in conjunction with auth_client_id (if required).
auth_keycloak_url
required
URL to the Keycloak instance.

aliases: url
auth_password
required
Password to authenticate for API access with.

aliases: password
auth_realm
required
Keycloak realm name to authenticate to for API access.
auth_username
required
Username to authenticate for API access with.

aliases: username
authorization_services_enabled
Are authorization services enabled for this client or not (OpenID connect). This is 'authorizationServicesEnabled' in the Keycloak REST API.

aliases: authorizationServicesEnabled
authorization_settings
a data structure defining the authorization settings for this client. For reference, please see the Keycloak API docs at http://www.keycloak.org/docs-api/3.3/rest-api/index.html#_resourceserverrepresentation. This is 'authorizationSettings' in the Keycloak REST API.

aliases: authorizationSettings
base_url
Default URL to use when the auth server needs to redirect or link back to the client This is 'baseUrl' in the Keycloak REST API.

aliases: baseUrl
bearer_only
The access type of this client is bearer-only. This is 'bearerOnly' in the Keycloak REST API.

aliases: bearerOnly
client_authenticator_type
    Choices:
  • client-secret
  • client-jwt
How do clients authenticate with the auth server? Either client-secret or client-jwt can be chosen. When using client-secret, the module parameter secret can set it, while for client-jwt, you can use the keys use.jwks.url, jwks.url, and jwt.credential.certificate in the attributes module parameter to configure its behavior. This is 'clientAuthenticatorType' in the Keycloak REST API.

aliases: clientAuthenticatorType
client_id
Client id of client to be worked on. This is usually an alphanumeric name chosen by you. Either this or id is required. If you specify both, id takes precedence. This is 'clientId' in the Keycloak REST API.

aliases: clientId
client_template
Client template to use for this client. If it does not exist this field will silently be dropped. This is 'clientTemplate' in the Keycloak REST API.

aliases: clientTemplate
consent_required
If enabled, users have to consent to client access. This is 'consentRequired' in the Keycloak REST API.

aliases: consentRequired
default_roles
list of default roles for this client. If the client roles referenced do not exist yet, they will be created. This is 'defaultRoles' in the Keycloak REST API.

aliases: defaultRoles
description
Description of the client in Keycloak
direct_access_grants_enabled
Are direct access grants enabled for this client or not (OpenID connect). This is 'directAccessGrantsEnabled' in the Keycloak REST API.

aliases: directAccessGrantsEnabled
enabled
Is this client enabled or not?
frontchannel_logout
Is frontchannel logout enabled for this client or not. This is 'frontchannelLogout' in the Keycloak REST API.

aliases: frontchannelLogout
full_scope_allowed
Is the "Full Scope Allowed" feature set for this client or not. This is 'fullScopeAllowed' in the Keycloak REST API.

aliases: fullScopeAllowed
id
Id of client to be worked on. This is usually an UUID. Either this or client_id is required. If you specify both, this takes precedence.
implicit_flow_enabled
Enable implicit flow for this client or not (OpenID connect). This is 'implictFlowEnabled' in the Keycloak REST API.

aliases: implicitFlowEnabled
name
Name of the client (this is not the same as client_id)
node_re_registration_timeout
Cluster node re-registration timeout for this client. This is 'nodeReRegistrationTimeout' in the Keycloak REST API.

aliases: nodeReRegistrationTimeout
not_before
Revoke any tokens issued before this date for this client (this is a UNIX timestamp). This is 'notBefore' in the Keycloak REST API.

aliases: notBefore
protocol
    Choices:
  • openid-connect
  • saml
Type of client (either openid-connect or saml.
protocol_mappers
a list of dicts defining protocol mappers for this client. This is 'protocolMappers' in the Keycloak REST API.

aliases: protocolMappers
consentText
The human-readable name of the consent the user is presented to accept.
protocol
    Choices:
  • openid-connect
  • saml
This is either openid-connect or saml, this specifies for which protocol this protocol mapper is active.
name
The name of this protocol mapper.
config
Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value of protocolMapper and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing protocol mapper configuration through check-mode in the existing field.
protocolMapper
The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least
docker-v2-allow-all-mapper
oidc-address-mapper
oidc-full-name-mapper
oidc-group-membership-mapper
oidc-hardcoded-claim-mapper
oidc-hardcoded-role-mapper
oidc-role-name-mapper
oidc-script-based-protocol-mapper
oidc-sha256-pairwise-sub-mapper
oidc-usermodel-attribute-mapper
oidc-usermodel-client-role-mapper
oidc-usermodel-property-mapper
oidc-usermodel-realm-role-mapper
oidc-usersessionmodel-note-mapper
saml-group-membership-mapper
saml-hardcode-attribute-mapper
saml-hardcode-role-mapper
saml-role-list-mapper
saml-role-name-mapper
saml-user-attribute-mapper
saml-user-property-mapper
saml-user-session-note-mapper
An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers and looking under 'protocol-mapper'.
consentRequired
Specifies whether a user needs to provide consent to a client for this mapper to be active.
id
Usually a UUID specifying the internal ID of this protocol mapper instance.
public_client
Is the access type for this client public or not. This is 'publicClient' in the Keycloak REST API.

aliases: publicClient
realm
The realm to create the client in.
redirect_uris
Acceptable redirect URIs for this client. This is 'redirectUris' in the Keycloak REST API.

aliases: redirectUris
registered_nodes
dict of registered cluster nodes (with nodename as the key and last registration time as the value). This is 'registeredNodes' in the Keycloak REST API.

aliases: registeredNodes
registration_access_token
The registration access token provides access for clients to the client registration service. This is 'registrationAccessToken' in the Keycloak REST API.

aliases: registrationAccessToken
root_url
Root URL appended to relative URLs for this client This is 'rootUrl' in the Keycloak REST API.

aliases: rootUrl
secret
When using client_authenticator_type client-secret (the default), you can specify a secret here (otherwise one will be generated if it does not exit). If changing this secret, the module will not register a change currently (but the changed secret will be saved).
service_accounts_enabled
Are service accounts enabled for this client or not (OpenID connect). This is 'serviceAccountsEnabled' in the Keycloak REST API.

aliases: serviceAccountsEnabled
standard_flow_enabled
Enable standard flow for this client or not (OpenID connect). This is 'standardFlowEnabled' in the Keycloak REST API.

aliases: standardFlowEnabled
state
    Choices:
  • present ←
  • absent
State of the client
On present, the client will be created (or updated if it exists already).
On absent, the client will be removed if it exists
surrogate_auth_required
Whether or not surrogate auth is required. This is 'surrogateAuthRequired' in the Keycloak REST API.

aliases: surrogateAuthRequired
use_template_config
Whether or not to use configuration from the client_template. This is 'useTemplateConfig' in the Keycloak REST API.

aliases: useTemplateConfig
use_template_mappers
Whether or not to use mapper configuration from the client_template. This is 'useTemplateMappers' in the Keycloak REST API.

aliases: useTemplateMappers
use_template_scope
Whether or not to use scope configuration from the client_template. This is 'useTemplateScope' in the Keycloak REST API.

aliases: useTemplateScope
validate_certs
bool
    Choices:
  • no
  • yes ←
Verify TLS certificates (do not disable this in production).
web_origins
List of allowed CORS origins. This is 'webOrigins' in the Keycloak REST API.

aliases: webOrigins

Examples

- name: Create or update Keycloak client (minimal example)
  local_action:
    module: keycloak_client
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    client_id: test
    state: present

- name: Delete a Keycloak client
  local_action:
    module: keycloak_client
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    client_id: test
    state: absent

- name: Create or update a Keycloak client (with all the bells and whistles)
  local_action:
    module: keycloak_client
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    state: present
    realm: master
    client_id: test
    id: d8b127a3-31f6-44c8-a7e4-4ab9a3e78d95
    name: this_is_a_test
    description: Description of this wonderful client
    root_url: https://www.example.com/
    admin_url: https://www.example.com/admin_url
    base_url: basepath
    enabled: True
    client_authenticator_type: client-secret
    secret: REALLYWELLKEPTSECRET
    redirect_uris:
      - https://www.example.com/*
      - http://localhost:8888/
    web_origins:
      - https://www.example.com/*
    not_before: 1507825725
    bearer_only: False
    consent_required: False
    standard_flow_enabled: True
    implicit_flow_enabled: False
    direct_access_grants_enabled: False
    service_accounts_enabled: False
    authorization_services_enabled: False
    public_client: False
    frontchannel_logout: False
    protocol: openid-connect
    full_scope_allowed: false
    node_re_registration_timeout: -1
    client_template: test
    use_template_config: False
    use_template_scope: false
    use_template_mappers: no
    registered_nodes:
      node01.example.com: 1507828202
    registration_access_token: eyJWT_TOKEN
    surrogate_auth_required: false
    default_roles:
      - test01
      - test02
    protocol_mappers:
      - config:
          access.token.claim: True
          claim.name: "family_name"
          id.token.claim: True
          jsonType.label: String
          user.attribute: lastName
          userinfo.token.claim: True
        consentRequired: True
        consentText: "${familyName}"
        name: family name
        protocol: openid-connect
        protocolMapper: oidc-usermodel-property-mapper
      - config:
          attribute.name: Role
          attribute.nameformat: Basic
          single: false
        consentRequired: false
        name: role list
        protocol: saml
        protocolMapper: saml-role-list-mapper
    attributes:
      saml.authnstatement: True
      saml.client.signature: True
      saml.force.post.binding: True
      saml.server.signature: True
      saml.signature.algorithm: RSA_SHA256
      saml.signing.certificate: CERTIFICATEHERE
      saml.signing.private.key: PRIVATEKEYHERE
      saml_force_name_id_format: False
      saml_name_id_format: username
      saml_signature_canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#"
      user.info.response.signature.alg: RS256
      request.object.signature.alg: RS256
      use.jwks.url: true
      jwks.url: JWKS_URL_FOR_CLIENT_AUTH_JWT
      jwt.credential.certificate: JWT_CREDENTIAL_CERTIFICATE_FOR_CLIENT_AUTH

Return Values

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

Key Returned Description
end_state
dict
 always
client representation of client after module execution (sample is truncated)

Sample:
{'adminUrl': 'http://www.example.com/admin_url', 'attributes': {'request.object.signature.alg': 'RS256'}}
existing
dict
 always
client representation of existing client (sample is truncated)

Sample:
{'adminUrl': 'http://www.example.com/admin_url', 'attributes': {'request.object.signature.alg': 'RS256'}}
msg
string
 always
Message as to what action was taken

Sample:
Client testclient has been updated
proposed
dict
 always
client representation of proposed changes to client

Sample:
{'clientId': 'test'}


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • Eike Frost (@eikef)

Hint

If you notice any issues in this documentation you can edit this document to improve it.