community.general.keycloak_user_federation module – Allows administration of Keycloak user federations via Keycloak API
Note
This module is part of the community.general collection (version 9.5.1).
You might already have this collection installed if you are using the ansible package.
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 community.general.
To use it in a playbook, specify: community.general.keycloak_user_federation.
New in community.general 3.7.0
Synopsis
This module allows you to add, remove or modify Keycloak user federations 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/20.0.2/rest-api/index.html.
Parameters
Parameter |
Comments |
|---|---|
OpenID Connect Default: |
|
Client Secret to use in conjunction with |
|
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. |
|
The value of the config parameter Set to Set to Choices:
|
|
Dict specifying the configuration options for the provider; the contents differ depending on the value of The value |
|
Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The data about authenticated users will be provisioned from this LDAP server. Choices:
|
|
Enable/disable possibility of username/password authentication against Kerberos database. Choices:
|
|
Type of the Authentication method used during LDAP Bind operation. It is used in most of the requests sent to the LDAP server. Choices:
|
|
Count of LDAP users to be imported from LDAP to Keycloak within a single transaction. Default: |
|
Password of LDAP admin. |
|
DN of LDAP user which will be used by Keycloak to access LDAP server. |
|
Cache Policy for this storage provider. Choices:
|
|
Period for synchronization of changed or newly created LDAP users in seconds. Default: |
|
Determines if Keycloak should use connection pooling for accessing LDAP server. Choices:
|
|
A list of space-separated authentication types of connections that may be pooled. Choices:
|
|
A string that indicates the level of debug output to produce. Example valid values are |
|
The number of connections per connection identity to create when initially creating a connection for the identity. |
|
The maximum number of connections per connection identity that can be maintained concurrently. |
|
The preferred number of connections per connection identity that should be maintained concurrently. |
|
A list of space-separated protocol types of connections that may be pooled. Valid types are |
|
The number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool. |
|
LDAP Connection Timeout in milliseconds. |
|
Connection URL to your LDAP server. |
|
Additional LDAP Filter for filtering searched users. Leave this empty if you don’t need additional filter. |
|
Enable/disable debug logging to standard output for Krb5LoginModule. Choices:
|
|
Choices:
|
|
Enable/disable this user federation. Choices:
|
|
Day of the week the entry will become invalid on. |
|
Hour of day the entry will become invalid on. |
|
Minute of day the entry will become invalid on. |
|
Period for full synchronization in seconds. Default: |
|
If Choices:
|
|
Name of kerberos realm. |
|
Location of Kerberos KeyTab file containing the credentials of server principal. For example |
|
Name of the LDAP attribute, which refers to Kerberos principal. This is used to lookup appropriate LDAP user after successful Kerberos/SPNEGO authentication in Keycloak. When this is empty, the LDAP user will be looked based on LDAP username corresponding to the first part of his Kerberos principal. For instance, for principal |
|
Max lifespan of cache entry in milliseconds. |
|
Does the LDAP server support pagination. Choices:
|
|
Priority of provider when doing a user lookup. Lowest first. Default: |
|
Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it’s the same as Username LDAP attribute, however it is not required. For example for Active directory, it is common to use |
|
LDAP Read Timeout in milliseconds. This timeout applies for LDAP read operations. |
|
Specifies if LDAP referrals should be followed or ignored. Please note that enabling referrals can slow down authentication as it allows the LDAP server to decide which other LDAP servers to use. This could potentially include untrusted servers. Choices:
|
|
For one level, the search applies only for users in the DNs specified by User DNs. For subtree, the search applies to the whole subtree. See LDAP documentation for more details. Choices:
|
|
Full name of server principal for HTTP service including server and domain name. For example |
|
Encrypts the connection to LDAP using STARTTLS, which will disable connection pooling. Choices:
|
|
Should newly created users be created within LDAP store? Priority effects which provider is chosen to sync the new user. Choices:
|
|
If enabled, email provided by this provider is not verified even if verification is enabled for the realm. Choices:
|
|
Update profile on first login. Choices:
|
|
Use Kerberos login module for authenticate username/password against Kerberos server instead of authenticating against LDAP server with Directory Service API. Choices:
|
|
Use the LDAPv3 Password Modify Extended Operation (RFC-3062). The password modify extended operation usually requires that LDAP user already has password in the LDAP server. So when this is used with ‘Sync Registrations’, it can be good to add also ‘Hardcoded LDAP attribute mapper’ with randomly generated initial password. Choices:
|
|
Name of LDAP attribute, which is mapped as Keycloak username. For many LDAP server vendors it can be |
|
All values of LDAP objectClass attribute for users in LDAP divided by comma. For example |
|
Full DN of LDAP tree where your users are. This DN is the parent of LDAP users. |
|
Specifies whether LDAP connection will use the truststore SPI with the truststore configured in standalone.xml/domain.xml. Choices:
|
|
Name of LDAP attribute, which is used as unique object identifier (UUID) for objects in LDAP. For many LDAP server vendors, it is |
|
Determines if Keycloak should validate the password with the realm password policy before updating it. Choices:
|
|
LDAP vendor (provider). Use short name. For instance, write |
|
Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: |
|
Configures the HTTP User-Agent header. Default: |
|
The unique ID for this user federation. If left empty, the user federation will be searched by its |
|
A list of dicts defining mappers associated with this Identity Provider. |
|
Dict specifying the configuration options for the mapper; the contents differ depending on the value of identityProviderMapper. |
|
Unique ID of this mapper. |
|
Name of the mapper. If no ID is given, the mapper will be searched by name. |
|
Unique ID for the parent of this mapper. ID of the user federation will automatically be used if left blank. |
|
The mapper type for this mapper (for instance |
|
Component type for this mapper. Default: |
|
Display name of provider when linked in admin console. |
|
Unique ID for the parent of this user federation. Realm ID will be automatically used if left blank. |
|
Provider for this user federation. Built-in providers are |
|
Component type for user federation (only supported value is Default: |
|
The Keycloak realm under which this user federation resides. Default: |
|
Remove mappers that are not specified in the configuration for this federation. Set to Choices:
|
|
State of the user federation. On On Choices:
|
|
Authentication token for Keycloak API. |
|
Verify TLS certificates (do not disable this in production). Choices:
|
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 LDAP user federation
community.general.keycloak_user_federation:
auth_keycloak_url: https://keycloak.example.com/auth
auth_realm: master
auth_username: admin
auth_password: password
realm: my-realm
name: my-ldap
state: present
provider_id: ldap
provider_type: org.keycloak.storage.UserStorageProvider
config:
priority: 0
enabled: true
cachePolicy: DEFAULT
batchSizeForSync: 1000
editMode: READ_ONLY
importEnabled: true
syncRegistrations: false
vendor: other
usernameLDAPAttribute: uid
rdnLDAPAttribute: uid
uuidLDAPAttribute: entryUUID
userObjectClasses: inetOrgPerson, organizationalPerson
connectionUrl: ldaps://ldap.example.com:636
usersDn: ou=Users,dc=example,dc=com
authType: simple
bindDn: cn=directory reader
bindCredential: password
searchScope: 1
validatePasswordPolicy: false
trustEmail: false
useTruststoreSpi: ldapsOnly
connectionPooling: true
pagination: true
allowKerberosAuthentication: false
debug: false
useKerberosForPasswordAuthentication: false
mappers:
- name: "full name"
providerId: "full-name-ldap-mapper"
providerType: "org.keycloak.storage.ldap.mappers.LDAPStorageMapper"
config:
ldap.full.name.attribute: cn
read.only: true
write.only: false
- name: Create Kerberos user federation
community.general.keycloak_user_federation:
auth_keycloak_url: https://keycloak.example.com/auth
auth_realm: master
auth_username: admin
auth_password: password
realm: my-realm
name: my-kerberos
state: present
provider_id: kerberos
provider_type: org.keycloak.storage.UserStorageProvider
config:
priority: 0
enabled: true
cachePolicy: DEFAULT
kerberosRealm: EXAMPLE.COM
serverPrincipal: HTTP/[email protected]
keyTab: keytab
allowPasswordAuthentication: false
updateProfileFirstLogin: false
- name: Create sssd user federation
community.general.keycloak_user_federation:
auth_keycloak_url: https://keycloak.example.com/auth
auth_realm: master
auth_username: admin
auth_password: password
realm: my-realm
name: my-sssd
state: present
provider_id: sssd
provider_type: org.keycloak.storage.UserStorageProvider
config:
priority: 0
enabled: true
cachePolicy: DEFAULT
- name: Delete user federation
community.general.keycloak_user_federation:
auth_keycloak_url: https://keycloak.example.com/auth
auth_realm: master
auth_username: admin
auth_password: password
realm: my-realm
name: my-federation
state: absent
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Representation of user federation after module execution. Returned: on success Sample: |
|
Representation of existing user federation. Returned: always Sample: |
|
Message as to what action was taken. Returned: always Sample: |
|
Representation of proposed user federation. Returned: always Sample: |