community.general.keycloak_client – Allows administration of Keycloak clients via Keycloak API¶
Note
This plugin is part of the community.general collection (version 2.5.1).
To install it use: ansible-galaxy collection install community.general
.
To use it in a playbook, specify: community.general.keycloak_client
.
Synopsis¶
This 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 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.
Parameters¶
Parameter | Choices/Defaults | Comments | |
---|---|---|---|
admin_url
string
|
URL to the admin interface of the client This is 'adminUrl' in the Keycloak REST API.
aliases: adminUrl |
||
attributes
dictionary
|
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.
|
||
jwks.url
string
|
For OpenID-Connect clients, URL where client keys in JWK are stored.
|
||
jwt.credential.certificate
string
|
For OpenID-Connect clients, client certificate for validating JWT issued by client and signed by its key, base64-encoded.
|
||
request.object.signature.alg
string
|
For OpenID-Connect clients, JWA algorithm which the client needs to use when sending OIDC request object. One of
any , none , RS256 . |
||
saml.authnstatement
string
|
For SAML clients, boolean specifying whether or not a statement containing method and timestamp should be included in the login response.
|
||
saml.client.signature
string
|
For SAML clients, boolean specifying whether a client signature is required and validated.
|
||
saml.encrypt
string
|
Boolean specifying whether SAML assertions should be encrypted with the client's public key.
|
||
saml.force.post.binding
string
|
For SAML clients, boolean specifying whether always to use POST binding for responses.
|
||
saml.onetimeuse.condition
string
|
For SAML clients, boolean specifying whether a OneTimeUse condition should be included in login responses.
|
||
saml.server.signature
string
|
Boolean specifying whether SAML documents should be signed by the realm.
|
||
saml.server.signature.keyinfo.ext
string
|
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
string
|
Signature algorithm used to sign SAML documents. One of
RSA_SHA256 , RSA_SHA1 , RSA_SHA512 , or DSA_SHA1 . |
||
saml.signing.certificate
string
|
SAML signing key certificate, base64-encoded.
|
||
saml.signing.private.key
string
|
SAML signing key private key, base64-encoded.
|
||
saml_assertion_consumer_url_post
string
|
SAML POST Binding URL for the client's assertion consumer service (login responses).
|
||
saml_assertion_consumer_url_redirect
string
|
SAML Redirect Binding URL for the client's assertion consumer service (login responses).
|
||
saml_force_name_id_format
string
|
For SAML clients, Boolean specifying whether to ignore requested NameID subject format and using the configured one instead.
|
||
saml_name_id_format
string
|
For SAML clients, the NameID format to use (one of
username , email , transient , or persistent ) |
||
saml_signature_canonicalization_method
string
|
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_single_logout_service_url_post
string
|
SAML POST binding url for the client's single logout service.
|
||
saml_single_logout_service_url_redirect
string
|
SAML redirect binding url for the client's single logout service.
|
||
use.jwks.url
string
|
For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to obtain client public keys.
|
||
user.info.response.signature.alg
string
|
For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of
RS256 or unsigned . |
||
auth_client_id
string
|
Default: "admin-cli"
|
OpenID Connect client_id to authenticate to the API with.
|
|
auth_client_secret
string
|
Client Secret to use in conjunction with auth_client_id (if required).
|
||
auth_keycloak_url
string
/ required
|
URL to the Keycloak instance.
aliases: url |
||
auth_password
string
/ required
|
Password to authenticate for API access with.
aliases: password |
||
auth_realm
string
/ required
|
Keycloak realm name to authenticate to for API access.
|
||
auth_username
string
/ required
|
Username to authenticate for API access with.
aliases: username |
||
authorization_services_enabled
boolean
|
|
Are authorization services enabled for this client or not (OpenID connect). This is 'authorizationServicesEnabled' in the Keycloak REST API.
aliases: authorizationServicesEnabled |
|
authorization_settings
dictionary
|
a data structure defining the authorization settings for this client. For reference, please see the Keycloak API docs at https://www.keycloak.org/docs-api/8.0/rest-api/index.html#_resourceserverrepresentation. This is 'authorizationSettings' in the Keycloak REST API.
aliases: authorizationSettings |
||
base_url
string
|
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
boolean
|
|
The access type of this client is bearer-only. This is 'bearerOnly' in the Keycloak REST API.
aliases: bearerOnly |
|
client_authenticator_type
string
|
|
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
string
|
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
string
|
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
boolean
|
|
If enabled, users have to consent to client access. This is 'consentRequired' in the Keycloak REST API.
aliases: consentRequired |
|
default_roles
list
/ elements=string
|
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
string
|
Description of the client in Keycloak
|
||
direct_access_grants_enabled
boolean
|
|
Are direct access grants enabled for this client or not (OpenID connect). This is 'directAccessGrantsEnabled' in the Keycloak REST API.
aliases: directAccessGrantsEnabled |
|
enabled
boolean
|
|
Is this client enabled or not?
|
|
frontchannel_logout
boolean
|
|
Is frontchannel logout enabled for this client or not. This is 'frontchannelLogout' in the Keycloak REST API.
aliases: frontchannelLogout |
|
full_scope_allowed
boolean
|
|
Is the "Full Scope Allowed" feature set for this client or not. This is 'fullScopeAllowed' in the Keycloak REST API.
aliases: fullScopeAllowed |
|
id
string
|
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
boolean
|
|
Enable implicit flow for this client or not (OpenID connect). This is 'implicitFlowEnabled' in the Keycloak REST API.
aliases: implicitFlowEnabled |
|
name
string
|
Name of the client (this is not the same as client_id)
|
||
node_re_registration_timeout
integer
|
Cluster node re-registration timeout for this client. This is 'nodeReRegistrationTimeout' in the Keycloak REST API.
aliases: nodeReRegistrationTimeout |
||
not_before
integer
|
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
string
|
|
Type of client (either
openid-connect or saml . |
|
protocol_mappers
list
/ elements=dictionary
|
a list of dicts defining protocol mappers for this client. This is 'protocolMappers' in the Keycloak REST API.
aliases: protocolMappers |
||
config
dictionary
|
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.
|
||
consentRequired
boolean
|
|
Specifies whether a user needs to provide consent to a client for this mapper to be active.
|
|
consentText
string
|
The human-readable name of the consent the user is presented to accept.
|
||
id
string
|
Usually a UUID specifying the internal ID of this protocol mapper instance.
|
||
name
string
|
The name of this protocol mapper.
|
||
protocol
string
|
|
This is either
openid-connect or saml , this specifies for which protocol this protocol mapper is active. |
|
protocolMapper
string
|
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'.
|
||
public_client
boolean
|
|
Is the access type for this client public or not. This is 'publicClient' in the Keycloak REST API.
aliases: publicClient |
|
realm
string
|
Default: "master"
|
The realm to create the client in.
|
|
redirect_uris
list
/ elements=string
|
Acceptable redirect URIs for this client. This is 'redirectUris' in the Keycloak REST API.
aliases: redirectUris |
||
registered_nodes
dictionary
|
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
string
|
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
string
|
Root URL appended to relative URLs for this client This is 'rootUrl' in the Keycloak REST API.
aliases: rootUrl |
||
secret
string
|
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
boolean
|
|
Are service accounts enabled for this client or not (OpenID connect). This is 'serviceAccountsEnabled' in the Keycloak REST API.
aliases: serviceAccountsEnabled |
|
standard_flow_enabled
boolean
|
|
Enable standard flow for this client or not (OpenID connect). This is 'standardFlowEnabled' in the Keycloak REST API.
aliases: standardFlowEnabled |
|
state
string
|
|
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
boolean
|
|
Whether or not surrogate auth is required. This is 'surrogateAuthRequired' in the Keycloak REST API.
aliases: surrogateAuthRequired |
|
use_template_config
boolean
|
|
Whether or not to use configuration from the client_template. This is 'useTemplateConfig' in the Keycloak REST API.
aliases: useTemplateConfig |
|
use_template_mappers
boolean
|
|
Whether or not to use mapper configuration from the client_template. This is 'useTemplateMappers' in the Keycloak REST API.
aliases: useTemplateMappers |
|
use_template_scope
boolean
|
|
Whether or not to use scope configuration from the client_template. This is 'useTemplateScope' in the Keycloak REST API.
aliases: useTemplateScope |
|
validate_certs
boolean
|
|
Verify TLS certificates (do not disable this in production).
|
|
web_origins
list
/ elements=string
|
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:
Authors¶
Eike Frost (@eikef)