Try SpotterAllows administration of Keycloak clients via Keycloak API
Authors: Eike Frost (@eikef)
Install with ansible-galaxy collection install community.general:==8.5.0
collections:
- name: community.general
version: 8.5.0This module allows the administration of Keycloak clients 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.
The names of module options are snake_cased versions of the camelCase ones found in the Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html). Aliases are provided so camelCased versions can be used as well.
The Keycloak API does not always sanity check inputs e.g. you can set SAML-specific settings on an OpenID Connect client for instance and vice versa. Be careful. If you do not specify a setting, usually a sensible default is chosen.
- name: Create or update Keycloak client (minimal example), authentication with credentials
community.general.keycloak_client:
auth_keycloak_url: https://auth.example.com/auth
auth_realm: master
auth_username: USERNAME
auth_password: PASSWORD
client_id: test
state: present
delegate_to: localhost
- name: Create or update Keycloak client (minimal example), authentication with token
community.general.keycloak_client:
auth_client_id: admin-cli
auth_keycloak_url: https://auth.example.com/auth
auth_realm: master
token: TOKEN
client_id: test
state: present
delegate_to: localhost
- name: Delete a Keycloak client
community.general.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
delegate_to: localhost
- name: Create or update a Keycloak client (with all the bells and whistles)
community.general.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: false
always_display_in_console: true
registered_nodes:
node01.example.com: 1507828202
registration_access_token: eyJWT_TOKEN
surrogate_auth_required: false
default_roles:
- test01
- test02
authentication_flow_binding_overrides:
browser: 4c90336b-bf1d-4b87-916d-3677ba4e5fbb
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
delegate_to: localhost
id:
description:
- Id of client to be worked on. This is usually an UUID. Either this or O(client_id)
is required. If you specify both, this takes precedence.
type: str
name:
description:
- Name of the client (this is not the same as O(client_id)).
type: str
realm:
default: master
description:
- The realm to create the client in.
type: str
state:
choices:
- present
- absent
default: present
description:
- State of the client
- On V(present), the client will be created (or updated if it exists already).
- On V(absent), the client will be removed if it exists
type: str
token:
description:
- Authentication token for Keycloak API.
type: str
version_added: 3.0.0
version_added_collection: community.general
secret:
description:
- When using O(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).
type: str
enabled:
description:
- Is this client enabled or not?
type: bool
base_url:
aliases:
- baseUrl
description:
- 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.
type: str
protocol:
choices:
- openid-connect
- saml
description:
- Type of client.
- At creation only, default value will be V(openid-connect) if O(protocol) is omitted.
type: str
root_url:
aliases:
- rootUrl
description:
- Root URL appended to relative URLs for this client. This is 'rootUrl' in the Keycloak
REST API.
type: str
admin_url:
aliases:
- adminUrl
description:
- URL to the admin interface of the client. This is 'adminUrl' in the Keycloak REST
API.
type: str
client_id:
aliases:
- clientId
description:
- Client id of client to be worked on. This is usually an alphanumeric name chosen
by you. Either this or O(id) is required. If you specify both, O(id) takes precedence.
This is 'clientId' in the Keycloak REST API.
type: str
attributes:
description:
- 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.
suboptions:
jwks.url:
description:
- For OpenID-Connect clients, URL where client keys in JWK are stored.
jwt.credential.certificate:
description:
- For OpenID-Connect clients, client certificate for validating JWT issued by
client and signed by its key, base64-encoded.
request.object.signature.alg:
description:
- For OpenID-Connect clients, JWA algorithm which the client needs to use when
sending OIDC request object. One of V(any), V(none), V(RS256).
saml.authnstatement:
description:
- For SAML clients, boolean specifying whether or not a statement containing method
and timestamp should be included in the login response.
saml.client.signature:
description:
- For SAML clients, boolean specifying whether a client signature is required
and validated.
saml.encrypt:
description:
- Boolean specifying whether SAML assertions should be encrypted with the client's
public key.
saml.force.post.binding:
description:
- For SAML clients, boolean specifying whether always to use POST binding for
responses.
saml.onetimeuse.condition:
description:
- For SAML clients, boolean specifying whether a OneTimeUse condition should be
included in login responses.
saml.server.signature:
description:
- Boolean specifying whether SAML documents should be signed by the realm.
saml.server.signature.keyinfo.ext:
description:
- 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.signature.algorithm:
description:
- Signature algorithm used to sign SAML documents. One of V(RSA_SHA256), V(RSA_SHA1),
V(RSA_SHA512), or V(DSA_SHA1).
saml.signing.certificate:
description:
- SAML signing key certificate, base64-encoded.
saml.signing.private.key:
description:
- SAML signing key private key, base64-encoded.
saml_assertion_consumer_url_post:
description:
- SAML POST Binding URL for the client's assertion consumer service (login responses).
saml_assertion_consumer_url_redirect:
description:
- SAML Redirect Binding URL for the client's assertion consumer service (login
responses).
saml_force_name_id_format:
description:
- For SAML clients, Boolean specifying whether to ignore requested NameID subject
format and using the configured one instead.
saml_name_id_format:
description:
- For SAML clients, the NameID format to use (one of V(username), V(email), V(transient),
or V(persistent))
saml_signature_canonicalization_method:
description:
- SAML signature canonicalization method. This is one of four values, namely V(http://www.w3.org/2001/10/xml-exc-c14n#)
for EXCLUSIVE, V(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS,
V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) for INCLUSIVE, and V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments)
for INCLUSIVE_WITH_COMMENTS.
saml_single_logout_service_url_post:
description:
- SAML POST binding url for the client's single logout service.
saml_single_logout_service_url_redirect:
description:
- SAML redirect binding url for the client's single logout service.
use.jwks.url:
description:
- For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to
obtain client public keys.
user.info.response.signature.alg:
description:
- For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses.
One of V(RS256) or V(unsigned).
type: dict
auth_realm:
description:
- Keycloak realm name to authenticate to for API access.
type: str
http_agent:
default: Ansible
description:
- Configures the HTTP User-Agent header.
type: str
version_added: 5.4.0
version_added_collection: community.general
not_before:
aliases:
- notBefore
description:
- Revoke any tokens issued before this date for this client (this is a UNIX timestamp).
This is 'notBefore' in the Keycloak REST API.
type: int
bearer_only:
aliases:
- bearerOnly
description:
- The access type of this client is bearer-only. This is 'bearerOnly' in the Keycloak
REST API.
type: bool
description:
description:
- Description of the client in Keycloak.
type: str
web_origins:
aliases:
- webOrigins
description:
- List of allowed CORS origins. This is 'webOrigins' in the Keycloak REST API.
elements: str
type: list
auth_password:
aliases:
- password
description:
- Password to authenticate for API access with.
type: str
auth_username:
aliases:
- username
description:
- Username to authenticate for API access with.
type: str
default_roles:
aliases:
- defaultRoles
description:
- 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.
elements: str
type: list
public_client:
aliases:
- publicClient
description:
- Is the access type for this client public or not. This is 'publicClient' in the
Keycloak REST API.
type: bool
redirect_uris:
aliases:
- redirectUris
description:
- Acceptable redirect URIs for this client. This is 'redirectUris' in the Keycloak
REST API.
elements: str
type: list
auth_client_id:
default: admin-cli
description:
- OpenID Connect C(client_id) to authenticate to the API with.
type: str
validate_certs:
default: true
description:
- Verify TLS certificates (do not disable this in production).
type: bool
client_template:
aliases:
- clientTemplate
description:
- 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.
type: str
consent_required:
aliases:
- consentRequired
description:
- If enabled, users have to consent to client access. This is 'consentRequired' in
the Keycloak REST API.
type: bool
protocol_mappers:
aliases:
- protocolMappers
description:
- a list of dicts defining protocol mappers for this client. This is 'protocolMappers'
in the Keycloak REST API.
elements: dict
suboptions:
config:
description:
- Dict specifying the configuration options for the protocol mapper; the contents
differ depending on the value of O(protocol_mappers[].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
RV(existing) field.
type: dict
consentRequired:
description:
- Specifies whether a user needs to provide consent to a client for this mapper
to be active.
type: bool
consentText:
description:
- The human-readable name of the consent the user is presented to accept.
type: str
id:
description:
- Usually a UUID specifying the internal ID of this protocol mapper instance.
type: str
name:
description:
- The name of this protocol mapper.
type: str
protocol:
choices:
- openid-connect
- saml
description:
- This specifies for which protocol this protocol mapper is active.
type: str
protocolMapper:
description:
- '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:'
- V(docker-v2-allow-all-mapper)
- V(oidc-address-mapper)
- V(oidc-full-name-mapper)
- V(oidc-group-membership-mapper)
- V(oidc-hardcoded-claim-mapper)
- V(oidc-hardcoded-role-mapper)
- V(oidc-role-name-mapper)
- V(oidc-script-based-protocol-mapper)
- V(oidc-sha256-pairwise-sub-mapper)
- V(oidc-usermodel-attribute-mapper)
- V(oidc-usermodel-client-role-mapper)
- V(oidc-usermodel-property-mapper)
- V(oidc-usermodel-realm-role-mapper)
- V(oidc-usersessionmodel-note-mapper)
- V(saml-group-membership-mapper)
- V(saml-hardcode-attribute-mapper)
- V(saml-hardcode-role-mapper)
- V(saml-role-list-mapper)
- V(saml-role-name-mapper)
- V(saml-user-attribute-mapper)
- V(saml-user-property-mapper)
- V(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'.
type: str
type: list
registered_nodes:
aliases:
- registeredNodes
description:
- dict of registered cluster nodes (with C(nodename) as the key and last registration
time as the value). This is 'registeredNodes' in the Keycloak REST API.
type: dict
auth_keycloak_url:
aliases:
- url
description:
- URL to the Keycloak instance.
required: true
type: str
auth_client_secret:
description:
- Client Secret to use in conjunction with O(auth_client_id) (if required).
type: str
connection_timeout:
default: 10
description:
- Controls the HTTP connections timeout period (in seconds) to Keycloak API.
type: int
version_added: 4.5.0
version_added_collection: community.general
full_scope_allowed:
aliases:
- fullScopeAllowed
description:
- Is the "Full Scope Allowed" feature set for this client or not. This is 'fullScopeAllowed'
in the Keycloak REST API.
type: bool
use_template_scope:
aliases:
- useTemplateScope
description:
- Whether or not to use scope configuration from the O(client_template). This is 'useTemplateScope'
in the Keycloak REST API.
type: bool
frontchannel_logout:
aliases:
- frontchannelLogout
description:
- Is frontchannel logout enabled for this client or not. This is 'frontchannelLogout'
in the Keycloak REST API.
type: bool
use_template_config:
aliases:
- useTemplateConfig
description:
- Whether or not to use configuration from the O(client_template). This is 'useTemplateConfig'
in the Keycloak REST API.
type: bool
use_template_mappers:
aliases:
- useTemplateMappers
description:
- Whether or not to use mapper configuration from the O(client_template). This is
'useTemplateMappers' in the Keycloak REST API.
type: bool
default_client_scopes:
aliases:
- defaultClientScopes
description:
- List of default client scopes.
elements: str
type: list
version_added: 4.7.0
version_added_collection: community.general
implicit_flow_enabled:
aliases:
- implicitFlowEnabled
description:
- Enable implicit flow for this client or not (OpenID connect). This is 'implicitFlowEnabled'
in the Keycloak REST API.
type: bool
standard_flow_enabled:
aliases:
- standardFlowEnabled
description:
- Enable standard flow for this client or not (OpenID connect). This is 'standardFlowEnabled'
in the Keycloak REST API.
type: bool
authorization_settings:
aliases:
- authorizationSettings
description:
- a data structure defining the authorization settings for this client. For reference,
please see the Keycloak API docs at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation).
This is 'authorizationSettings' in the Keycloak REST API.
type: dict
optional_client_scopes:
aliases:
- optionalClientScopes
description:
- List of optional client scopes.
elements: str
type: list
version_added: 4.7.0
version_added_collection: community.general
surrogate_auth_required:
aliases:
- surrogateAuthRequired
description:
- Whether or not surrogate auth is required. This is 'surrogateAuthRequired' in the
Keycloak REST API.
type: bool
service_accounts_enabled:
aliases:
- serviceAccountsEnabled
description:
- Are service accounts enabled for this client or not (OpenID connect). This is 'serviceAccountsEnabled'
in the Keycloak REST API.
type: bool
always_display_in_console:
aliases:
- alwaysDisplayInConsole
description:
- Whether or not to display this client in account console, even if the user does
not have an active session.
type: bool
version_added: 4.7.0
version_added_collection: community.general
client_authenticator_type:
aliases:
- clientAuthenticatorType
choices:
- client-secret
- client-jwt
description:
- How do clients authenticate with the auth server? Either V(client-secret) or V(client-jwt)
can be chosen. When using V(client-secret), the module parameter O(secret) can set
it, while for V(client-jwt), you can use the keys C(use.jwks.url), C(jwks.url),
and C(jwt.credential.certificate) in the O(attributes) module parameter to configure
its behavior.
- This is 'clientAuthenticatorType' in the Keycloak REST API.
type: str
registration_access_token:
aliases:
- registrationAccessToken
description:
- The registration access token provides access for clients to the client registration
service. This is 'registrationAccessToken' in the Keycloak REST API.
type: str
direct_access_grants_enabled:
aliases:
- directAccessGrantsEnabled
description:
- Are direct access grants enabled for this client or not (OpenID connect). This is
'directAccessGrantsEnabled' in the Keycloak REST API.
type: bool
node_re_registration_timeout:
aliases:
- nodeReRegistrationTimeout
description:
- Cluster node re-registration timeout for this client. This is 'nodeReRegistrationTimeout'
in the Keycloak REST API.
type: int
authorization_services_enabled:
aliases:
- authorizationServicesEnabled
description:
- Are authorization services enabled for this client or not (OpenID connect). This
is 'authorizationServicesEnabled' in the Keycloak REST API.
type: bool
authentication_flow_binding_overrides:
aliases:
- authenticationFlowBindingOverrides
description:
- Override realm authentication flow bindings.
type: dict
version_added: 3.4.0
version_added_collection: community.general
end_state:
description: Representation of client after module execution (sample is truncated).
returned: on success
sample:
adminUrl: http://www.example.com/admin_url
attributes:
request.object.signature.alg: RS256
type: dict
existing:
description: Representation of existing client (sample is truncated).
returned: always
sample:
adminUrl: http://www.example.com/admin_url
attributes:
request.object.signature.alg: RS256
type: dict
msg:
description: Message as to what action was taken.
returned: always
sample: Client testclient has been updated
type: str
proposed:
description: Representation of proposed client.
returned: always
sample:
clientId: test
type: dict