Try SpotterAllows administration of Keycloak user federations via Keycloak API
| "added in version" 3.7.0 of community.general"
Authors: Laurent Paumier (@laurpaum)
Install with ansible-galaxy collection install community.general:==8.5.0
collections:
- name: community.general
version: 8.5.0This 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 U(https://www.keycloak.org/docs-api/20.0.2/rest-api/index.html).
- 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/host.example.com@EXAMPLE.COM
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
id:
description:
- The unique ID for this user federation. If left empty, the user federation will
be searched by its O(name).
type: str
name:
description:
- Display name of provider when linked in admin console.
type: str
realm:
default: master
description:
- The Keycloak realm under which this user federation resides.
type: str
state:
choices:
- present
- absent
default: present
description:
- State of the user federation.
- On V(present), the user federation will be created if it does not yet exist, or
updated with the parameters you provide.
- On V(absent), the user federation 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
config:
description:
- Dict specifying the configuration options for the provider; the contents differ
depending on the value of O(provider_id). Examples are given below for V(ldap),
V(kerberos) and V(sssd). It is easiest to obtain valid config values by dumping
an already-existing user federation configuration through check-mode in the RV(existing)
field.
- The value V(sssd) has been supported since community.general 4.2.0.
suboptions:
allowKerberosAuthentication:
default: false
description:
- Enable/disable HTTP authentication of users with SPNEGO/Kerberos tokens. The
data about authenticated users will be provisioned from this LDAP server.
type: bool
allowPasswordAuthentication:
description:
- Enable/disable possibility of username/password authentication against Kerberos
database.
type: bool
authType:
choices:
- none
- simple
default: none
description:
- Type of the Authentication method used during LDAP Bind operation. It is used
in most of the requests sent to the LDAP server.
type: str
batchSizeForSync:
default: 1000
description:
- Count of LDAP users to be imported from LDAP to Keycloak within a single transaction.
type: int
bindCredential:
description:
- Password of LDAP admin.
type: str
bindDn:
description:
- DN of LDAP user which will be used by Keycloak to access LDAP server.
type: str
cachePolicy:
choices:
- DEFAULT
- EVICT_DAILY
- EVICT_WEEKLY
- MAX_LIFESPAN
- NO_CACHE
default: DEFAULT
description:
- Cache Policy for this storage provider.
type: str
changedSyncPeriod:
default: -1
description:
- Period for synchronization of changed or newly created LDAP users in seconds.
type: int
connectionPooling:
default: true
description:
- Determines if Keycloak should use connection pooling for accessing LDAP server.
type: bool
connectionPoolingAuthentication:
choices:
- none
- simple
- DIGEST-MD5
description:
- A list of space-separated authentication types of connections that may be pooled.
type: str
connectionPoolingDebug:
description:
- A string that indicates the level of debug output to produce. Example valid
values are V(fine) (trace connection creation and removal) and V(all) (all debugging
information).
type: str
connectionPoolingInitSize:
description:
- The number of connections per connection identity to create when initially creating
a connection for the identity.
type: int
connectionPoolingMaxSize:
description:
- The maximum number of connections per connection identity that can be maintained
concurrently.
type: int
connectionPoolingPrefSize:
description:
- The preferred number of connections per connection identity that should be maintained
concurrently.
type: int
connectionPoolingProtocol:
description:
- A list of space-separated protocol types of connections that may be pooled.
Valid types are V(plain) and V(ssl).
type: str
connectionPoolingTimeout:
description:
- The number of milliseconds that an idle connection may remain in the pool without
being closed and removed from the pool.
type: int
connectionTimeout:
description:
- LDAP Connection Timeout in milliseconds.
type: int
connectionUrl:
description:
- Connection URL to your LDAP server.
type: str
customUserSearchFilter:
description:
- Additional LDAP Filter for filtering searched users. Leave this empty if you
don't need additional filter.
type: str
debug:
description:
- Enable/disable debug logging to standard output for Krb5LoginModule.
type: bool
editMode:
choices:
- READ_ONLY
- WRITABLE
- UNSYNCED
description:
- V(READ_ONLY) is a read-only LDAP store. V(WRITABLE) means data will be synced
back to LDAP on demand. V(UNSYNCED) means user data will be imported, but not
synced back to LDAP.
type: str
enabled:
default: true
description:
- Enable/disable this user federation.
type: bool
evictionDay:
description:
- Day of the week the entry will become invalid on.
type: str
evictionHour:
description:
- Hour of day the entry will become invalid on.
type: str
evictionMinute:
description:
- Minute of day the entry will become invalid on.
type: str
fullSyncPeriod:
default: -1
description:
- Period for full synchronization in seconds.
type: int
importEnabled:
default: true
description:
- If V(true), LDAP users will be imported into Keycloak DB and synced by the configured
sync policies.
type: bool
kerberosRealm:
description:
- Name of kerberos realm.
type: str
keyTab:
description:
- Location of Kerberos KeyTab file containing the credentials of server principal.
For example V(/etc/krb5.keytab).
type: str
krbPrincipalAttribute:
description:
- 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 C(john@KEYCLOAK.ORG), it will assume that LDAP username is V(john).
type: str
version_added: 8.1.0
version_added_collection: community.general
maxLifespan:
description:
- Max lifespan of cache entry in milliseconds.
type: int
pagination:
default: true
description:
- Does the LDAP server support pagination.
type: bool
priority:
default: 0
description:
- Priority of provider when doing a user lookup. Lowest first.
type: int
rdnLDAPAttribute:
description:
- 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 V(cn) as RDN attribute
when username attribute might be V(sAMAccountName).
type: str
readTimeout:
description:
- LDAP Read Timeout in milliseconds. This timeout applies for LDAP read operations.
type: int
searchScope:
choices:
- '1'
- '2'
default: '1'
description:
- 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.
type: str
serverPrincipal:
description:
- Full name of server principal for HTTP service including server and domain name.
For example V(HTTP/host.foo.org@FOO.ORG). Use V(*) to accept any service principal
in the KeyTab file.
type: str
startTls:
default: false
description:
- Encrypts the connection to LDAP using STARTTLS, which will disable connection
pooling.
type: bool
syncRegistrations:
default: false
description:
- Should newly created users be created within LDAP store? Priority effects which
provider is chosen to sync the new user.
type: bool
trustEmail:
default: false
description:
- If enabled, email provided by this provider is not verified even if verification
is enabled for the realm.
type: bool
updateProfileFirstLogin:
description:
- Update profile on first login.
type: bool
useKerberosForPasswordAuthentication:
default: false
description:
- Use Kerberos login module for authenticate username/password against Kerberos
server instead of authenticating against LDAP server with Directory Service
API.
type: bool
usePasswordModifyExtendedOp:
default: false
description:
- 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.
type: bool
useTruststoreSpi:
choices:
- always
- ldapsOnly
- never
default: ldapsOnly
description:
- Specifies whether LDAP connection will use the truststore SPI with the truststore
configured in standalone.xml/domain.xml. V(always) means that it will always
use it. V(never) means that it will not use it. V(ldapsOnly) means that it will
use if your connection URL use ldaps. Note even if standalone.xml/domain.xml
is not configured, the default Java cacerts or certificate specified by C(javax.net.ssl.trustStore)
property will be used.
type: str
userObjectClasses:
description:
- All values of LDAP objectClass attribute for users in LDAP divided by comma.
For example V(inetOrgPerson, organizationalPerson). Newly created Keycloak users
will be written to LDAP with all those object classes and existing LDAP user
records are found just if they contain all those object classes.
type: str
usernameLDAPAttribute:
description:
- Name of LDAP attribute, which is mapped as Keycloak username. For many LDAP
server vendors it can be V(uid). For Active directory it can be V(sAMAccountName)
or V(cn). The attribute should be filled for all LDAP user records you want
to import from LDAP to Keycloak.
type: str
usersDn:
description:
- Full DN of LDAP tree where your users are. This DN is the parent of LDAP users.
type: str
uuidLDAPAttribute:
description:
- Name of LDAP attribute, which is used as unique object identifier (UUID) for
objects in LDAP. For many LDAP server vendors, it is V(entryUUID); however some
are different. For example for Active directory it should be V(objectGUID).
If your LDAP server does not support the notion of UUID, you can use any other
attribute that is supposed to be unique among LDAP users in tree.
type: str
validatePasswordPolicy:
default: false
description:
- Determines if Keycloak should validate the password with the realm password
policy before updating it.
type: bool
vendor:
description:
- LDAP vendor (provider).
- Use short name. For instance, write V(rhds) for "Red Hat Directory Server".
type: str
type: dict
mappers:
description:
- A list of dicts defining mappers associated with this Identity Provider.
elements: dict
suboptions:
config:
description:
- Dict specifying the configuration options for the mapper; the contents differ
depending on the value of I(identityProviderMapper).
type: dict
id:
description:
- Unique ID of this mapper.
type: str
name:
description:
- Name of the mapper. If no ID is given, the mapper will be searched by name.
type: str
parentId:
description:
- Unique ID for the parent of this mapper. ID of the user federation will automatically
be used if left blank.
type: str
providerId:
description:
- The mapper type for this mapper (for instance V(user-attribute-ldap-mapper)).
type: str
providerType:
default: org.keycloak.storage.ldap.mappers.LDAPStorageMapper
description:
- Component type for this mapper.
type: str
type: list
parent_id:
aliases:
- parentId
description:
- Unique ID for the parent of this user federation. Realm ID will be automatically
used if left blank.
type: str
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
provider_id:
aliases:
- providerId
description:
- Provider for this user federation. Built-in providers are V(ldap), V(kerberos),
and V(sssd). Custom user storage providers can also be used.
type: str
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
provider_type:
aliases:
- providerType
default: org.keycloak.storage.UserStorageProvider
description:
- Component type for user federation (only supported value is V(org.keycloak.storage.UserStorageProvider)).
type: str
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
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
end_state:
description: Representation of user federation after module execution.
returned: on success
sample:
config:
allowPasswordAuthentication: 'false'
cachePolicy: DEFAULT
enabled: 'true'
kerberosRealm: EXAMPLE.COM
keyTab: /etc/krb5.keytab
priority: '0'
serverPrincipal: HTTP/host.example.com@EXAMPLE.COM
updateProfileFirstLogin: 'false'
id: cf52ae4f-4471-4435-a0cf-bb620cadc122
mappers: []
name: kerberos
parentId: myrealm
providerId: kerberos
providerType: org.keycloak.storage.UserStorageProvider
type: dict
existing:
description: Representation of existing user federation.
returned: always
sample:
config:
allowKerberosAuthentication: 'false'
authType: simple
batchSizeForSync: '1000'
bindCredential: '**********'
bindDn: cn=directory reader
cachePolicy: DEFAULT
changedSyncPeriod: '-1'
connectionPooling: 'true'
connectionUrl: ldaps://ldap.example.com:636
debug: 'false'
editMode: READ_ONLY
enabled: 'true'
fullSyncPeriod: '-1'
importEnabled: 'true'
pagination: 'true'
priority: '0'
rdnLDAPAttribute: uid
searchScope: '1'
syncRegistrations: 'false'
trustEmail: 'false'
useKerberosForPasswordAuthentication: 'false'
useTruststoreSpi: ldapsOnly
userObjectClasses: inetOrgPerson, organizationalPerson
usernameLDAPAttribute: uid
usersDn: ou=Users,dc=example,dc=com
uuidLDAPAttribute: entryUUID
validatePasswordPolicy: 'false'
vendor: other
id: 01122837-9047-4ae4-8ca0-6e2e891a765f
mappers:
- config:
always.read.value.from.ldap: 'false'
is.mandatory.in.ldap: 'false'
ldap.attribute: mail
read.only: 'true'
user.model.attribute: email
id: 17d60ce2-2d44-4c2c-8b1f-1fba601b9a9f
name: email
parentId: 01122837-9047-4ae4-8ca0-6e2e891a765f
providerId: user-attribute-ldap-mapper
providerType: org.keycloak.storage.ldap.mappers.LDAPStorageMapper
name: myfed
parentId: myrealm
providerId: ldap
providerType: org.keycloak.storage.UserStorageProvider
type: dict
msg:
description: Message as to what action was taken.
returned: always
sample: No changes required to user federation 164bb483-c613-482e-80fe-7f1431308799.
type: str
proposed:
description: Representation of proposed user federation.
returned: always
sample:
config:
allowKerberosAuthentication: 'false'
authType: simple
batchSizeForSync: '1000'
bindCredential: '**********'
bindDn: cn=directory reader
cachePolicy: DEFAULT
connectionPooling: 'true'
connectionUrl: ldaps://ldap.example.com:636
debug: 'false'
editMode: READ_ONLY
enabled: 'true'
importEnabled: 'true'
pagination: 'true'
priority: '0'
rdnLDAPAttribute: uid
searchScope: '1'
syncRegistrations: 'false'
trustEmail: 'false'
useKerberosForPasswordAuthentication: 'false'
useTruststoreSpi: ldapsOnly
userObjectClasses: inetOrgPerson, organizationalPerson
usernameLDAPAttribute: uid
usersDn: ou=Users,dc=example,dc=com
uuidLDAPAttribute: entryUUID
validatePasswordPolicy: 'false'
vendor: other
name: ldap
providerId: ldap
providerType: org.keycloak.storage.UserStorageProvider
type: dict