keycloak_client – Allows administration of Keycloak clients 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.
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 |
Comments |
|---|---|
URL to the admin interface of the client. This is 'adminUrl' in the Keycloak REST API. |
|
Whether or not to display this client in account console, even if the user does not have an active session. Choices:
|
|
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. |
|
For OpenID-Connect clients, URL where client keys in JWK are stored. |
|
For OpenID-Connect clients, client certificate for validating JWT issued by client and signed by its key, base64-encoded. |
|
For OpenID-Connect clients, JWA algorithm which the client needs to use when sending OIDC request object. One of |
|
For SAML clients, boolean specifying whether or not a statement containing method and timestamp should be included in the login response. |
|
For SAML clients, boolean specifying whether a client signature is required and validated. |
|
Boolean specifying whether SAML assertions should be encrypted with the client's public key. |
|
For SAML clients, boolean specifying whether always to use POST binding for responses. |
|
For SAML clients, boolean specifying whether a OneTimeUse condition should be included in login responses. |
|
Boolean specifying whether SAML documents should be signed by the realm. |
|
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. |
|
Signature algorithm used to sign SAML documents. One of |
|
SAML signing key certificate, base64-encoded. |
|
SAML signing key private key, base64-encoded. |
|
SAML POST Binding URL for the client's assertion consumer service (login responses). |
|
SAML Redirect Binding URL for the client's assertion consumer service (login responses). |
|
For SAML clients, Boolean specifying whether to ignore requested NameID subject format and using the configured one instead. |
|
For SAML clients, the NameID format to use (one of |
|
SAML signature canonicalization method. This is one of four values, namely |
|
SAML POST binding url for the client's single logout service. |
|
SAML redirect binding url for the client's single logout service. |
|
For OpenID-Connect clients, boolean specifying whether to use a JWKS URL to obtain client public keys. |
|
For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of |
|
For OpenID-Connect clients, boolean specifying whether to allow Choices:
|
|
For OpenID-Connect clients, subject which will be used to authenticate the client. |
|
OpenID Connect client_id to authenticate to the API with. Default: |
|
Client Secret to use in conjunction with auth_client_id (if required). |
|
URL to the Keycloak instance. |
|
Password to authenticate for API access with. |
|
Keycloak realm name to authenticate to for API access. |
|
Username to authenticate for API access with. |
|
Override realm authentication flow bindings. |
|
Flow ID of the browser authentication flow.
|
|
Flow name of the browser authentication flow.
|
|
Flow ID of the direct grant authentication flow.
|
|
Flow name of the direct grant authentication flow.
|
|
Are authorization services enabled for this client or not (OpenID connect). This is 'authorizationServicesEnabled' in the Keycloak REST API. Choices:
|
|
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. |
|
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. |
|
The access type of this client is bearer-only. This is 'bearerOnly' in the Keycloak REST API. Choices:
|
|
How do clients authenticate with the auth server? Either This is 'clientAuthenticatorType' in the Keycloak REST API. Choices:
|
|
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. |
|
Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: |
|
If enabled, users have to consent to client access. This is 'consentRequired' in the Keycloak REST API. Choices:
|
|
List of default client scopes. |
|
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. |
|
Description of the client in Keycloak. |
|
Are direct access grants enabled for this client or not (OpenID connect). This is 'directAccessGrantsEnabled' in the Keycloak REST API. Choices:
|
|
Is this client enabled or not? Choices:
|
|
Is frontchannel logout enabled for this client or not. This is 'frontchannelLogout' in the Keycloak REST API. Choices:
|
|
Is the "Full Scope Allowed" feature set for this client or not. This is 'fullScopeAllowed' in the Keycloak REST API. Choices:
|
|
Configures the HTTP User-Agent header. Default: |
|
Id of client to be worked on. This is usually an UUID. Either this or |
|
Enable implicit flow for this client or not (OpenID connect). This is 'implicitFlowEnabled' in the Keycloak REST API. Choices:
|
|
Name of the client (this is not the same as |
|
Cluster node re-registration timeout for this client. This is 'nodeReRegistrationTimeout' in the Keycloak REST API. |
|
Revoke any tokens issued before this date for this client (this is a UNIX timestamp). This is 'notBefore' in the Keycloak REST API. |
|
List of optional client scopes. |
|
Type of client. At creation only, default value will be The Choices:
|
|
a list of dicts defining protocol mappers for this client. This is 'protocolMappers' in the Keycloak REST API. |
|
Dict specifying the configuration options for the protocol mapper; the contents differ depending on the value of |
|
Specifies whether a user needs to provide consent to a client for this mapper to be active. Choices:
|
|
The human-readable name of the consent the user is presented to accept. |
|
Usually a UUID specifying the internal ID of this protocol mapper instance. |
|
The name of this protocol mapper. |
|
This specifies for which protocol this protocol mapper is active. Choices:
|
|
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:
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'. |
|
Is the access type for this client public or not. This is 'publicClient' in the Keycloak REST API. Choices:
|
|
The realm to create the client in. Default: |
|
Acceptable redirect URIs for this client. This is 'redirectUris' in the Keycloak REST API. |
|
dict of registered cluster nodes (with |
|
The registration access token provides access for clients to the client registration service. This is 'registrationAccessToken' in the Keycloak REST API. |
|
Root URL appended to relative URLs for this client. This is 'rootUrl' in the Keycloak REST API. |
|
When using |
|
Are service accounts enabled for this client or not (OpenID connect). This is 'serviceAccountsEnabled' in the Keycloak REST API. Choices:
|
|
Enable standard flow for this client or not (OpenID connect). This is 'standardFlowEnabled' in the Keycloak REST API. Choices:
|
|
State of the client On On Choices:
|
|
Whether or not surrogate auth is required. This is 'surrogateAuthRequired' in the Keycloak REST API. Choices:
|
|
Authentication token for Keycloak API. |
|
Whether or not to use configuration from the Choices:
|
|
Whether or not to use mapper configuration from the Choices:
|
|
Whether or not to use scope configuration from the Choices:
|
|
Verify TLS certificates (do not disable this in production). Choices:
|
|
List of allowed CORS origins. This is 'webOrigins' in the Keycloak REST API. |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full |
Can run in |
|
Support: full |
Will return details on what has changed (or possibly needs changing in |
Examples
- name: Create or update Keycloak client (minimal example), authentication with credentials
middleware_automation.keycloak.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
middleware_automation.keycloak.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
middleware_automation.keycloak.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 (minimal example), with x509 authentication
middleware_automation.keycloak.keycloak_client:
auth_client_id: admin-cli
auth_keycloak_url: https://auth.example.com/auth
auth_realm: master
auth_username: USERNAME
auth_password: PASSWORD
realm: master
state: present
client_id: test
client_authenticator_type: client-x509
attributes:
x509.subjectdn: "CN=client"
x509.allow.regex.pattern.comparison: false
- name: Create or update a Keycloak client (with all the bells and whistles)
middleware_automation.keycloak.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
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Representation of client after module execution (sample is truncated). Returned: on success Sample: |
|
Representation of existing client (sample is truncated). Returned: always Sample: |
|
Message as to what action was taken. Returned: always Sample: |
|
Representation of proposed client. Returned: always Sample: |