community.general.keycloak_realm – Allows administration of Keycloak realm via Keycloak API

Note

This plugin is part of the community.general collection (version 4.2.0).

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_realm.

New in version 3.0.0: of community.general

Synopsis

  • This module allows the administration of Keycloak realm via the Keycloak REST API. It requires access to the REST API via OpenID Connect; the user connecting and the realm 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 realm 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
access_code_lifespan
integer
The realm access code lifespan.

aliases: accessCodeLifespan
access_code_lifespan_login
integer
The realm access code lifespan login.

aliases: accessCodeLifespanLogin
access_code_lifespan_user_action
integer
The realm access code lifespan user action.

aliases: accessCodeLifespanUserAction
access_token_lifespan
integer
The realm access token lifespan.

aliases: accessTokenLifespan
access_token_lifespan_for_implicit_flow
integer
The realm access token lifespan for implicit flow.

aliases: accessTokenLifespanForImplicitFlow
account_theme
string
The realm account theme.

aliases: accountTheme
action_token_generated_by_admin_lifespan
integer
The realm action token generated by admin lifespan.

aliases: actionTokenGeneratedByAdminLifespan
action_token_generated_by_user_lifespan
integer
The realm action token generated by user lifespan.

aliases: actionTokenGeneratedByUserLifespan
admin_events_details_enabled
boolean
    Choices:
  • no
  • yes
The realm admin events details enabled.

aliases: adminEventsDetailsEnabled
admin_events_enabled
boolean
    Choices:
  • no
  • yes
The realm admin events enabled.

aliases: adminEventsEnabled
admin_theme
string
The realm admin theme.

aliases: adminTheme
attributes
dictionary
The realm attributes.
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
Password to authenticate for API access with.

aliases: password
auth_realm
string
Keycloak realm name to authenticate to for API access.
auth_username
string
Username to authenticate for API access with.

aliases: username
browser_flow
string
The realm browser flow.

aliases: browserFlow
browser_security_headers
dictionary
The realm browser security headers.

aliases: browserSecurityHeaders
brute_force_protected
boolean
    Choices:
  • no
  • yes
The realm brute force protected.

aliases: bruteForceProtected
client_authentication_flow
string
The realm client authentication flow.

aliases: clientAuthenticationFlow
client_scope_mappings
dictionary
The realm client scope mappings.

aliases: clientScopeMappings
default_default_client_scopes
list / elements=dictionary
The realm default default client scopes.

aliases: defaultDefaultClientScopes
default_groups
list / elements=dictionary
The realm default groups.

aliases: defaultGroups
default_locale
string
The realm default locale.

aliases: defaultLocale
default_optional_client_scopes
list / elements=dictionary
The realm default optional client scopes.

aliases: defaultOptionalClientScopes
default_roles
list / elements=dictionary
The realm default roles.

aliases: defaultRoles
default_signature_algorithm
string
The realm default signature algorithm.

aliases: defaultSignatureAlgorithm
direct_grant_flow
string
The realm direct grant flow.

aliases: directGrantFlow
display_name
string
The realm display name.

aliases: displayName
display_name_html
string
The realm display name HTML.

aliases: displayNameHtml
docker_authentication_flow
string
The realm docker authentication flow.

aliases: dockerAuthenticationFlow
duplicate_emails_allowed
boolean
    Choices:
  • no
  • yes
The realm duplicate emails allowed option.

aliases: duplicateEmailsAllowed
edit_username_allowed
boolean
    Choices:
  • no
  • yes
The realm edit username allowed option.

aliases: editUsernameAllowed
email_theme
string
The realm email theme.

aliases: emailTheme
enabled
boolean
    Choices:
  • no
  • yes
The realm enabled option.
enabled_event_types
list / elements=string
The realm enabled event types.

aliases: enabledEventTypes
events_enabled
boolean
added in 3.6.0 of community.general
    Choices:
  • no
  • yes
Enables or disables login events for this realm.

aliases: eventsEnabled
events_expiration
integer
The realm events expiration.

aliases: eventsExpiration
events_listeners
list / elements=string
The realm events listeners.

aliases: eventsListeners
failure_factor
integer
The realm failure factor.

aliases: failureFactor
id
string
The realm to create.
internationalization_enabled
boolean
    Choices:
  • no
  • yes
The realm internationalization enabled option.

aliases: internationalizationEnabled
login_theme
string
The realm login theme.

aliases: loginTheme
login_with_email_allowed
boolean
    Choices:
  • no
  • yes
The realm login with email allowed option.

aliases: loginWithEmailAllowed
max_delta_time_seconds
integer
The realm max delta time in seconds.

aliases: maxDeltaTimeSeconds
max_failure_wait_seconds
integer
The realm max failure wait in seconds.

aliases: maxFailureWaitSeconds
minimum_quick_login_wait_seconds
integer
The realm minimum quick login wait in seconds.

aliases: minimumQuickLoginWaitSeconds
not_before
integer
The realm not before.

aliases: notBefore
offline_session_idle_timeout
integer
The realm offline session idle timeout.

aliases: offlineSessionIdleTimeout
offline_session_max_lifespan
integer
The realm offline session max lifespan.

aliases: offlineSessionMaxLifespan
offline_session_max_lifespan_enabled
boolean
    Choices:
  • no
  • yes
The realm offline session max lifespan enabled option.

aliases: offlineSessionMaxLifespanEnabled
otp_policy_algorithm
string
The realm otp policy algorithm.

aliases: otpPolicyAlgorithm
otp_policy_digits
integer
The realm otp policy digits.

aliases: otpPolicyDigits
otp_policy_initial_counter
integer
The realm otp policy initial counter.

aliases: otpPolicyInitialCounter
otp_policy_look_ahead_window
integer
The realm otp policy look ahead window.

aliases: otpPolicyLookAheadWindow
otp_policy_period
integer
The realm otp policy period.

aliases: otpPolicyPeriod
otp_policy_type
string
The realm otp policy type.

aliases: otpPolicyType
otp_supported_applications
list / elements=string
The realm otp supported applications.

aliases: otpSupportedApplications
password_policy
string
The realm password policy.

aliases: passwordPolicy
permanent_lockout
boolean
    Choices:
  • no
  • yes
The realm permanent lockout.

aliases: permanentLockout
quick_login_check_milli_seconds
integer
The realm quick login check in milliseconds.

aliases: quickLoginCheckMilliSeconds
realm
string
The realm name.
refresh_token_max_reuse
integer
The realm refresh token max reuse.

aliases: refreshTokenMaxReuse
registration_allowed
boolean
    Choices:
  • no
  • yes
The realm registration allowed option.

aliases: registrationAllowed
registration_email_as_username
boolean
    Choices:
  • no
  • yes
The realm registration email as username option.

aliases: registrationEmailAsUsername
registration_flow
string
The realm registration flow.

aliases: registrationFlow
remember_me
boolean
    Choices:
  • no
  • yes
The realm remember me option.

aliases: rememberMe
reset_credentials_flow
string
The realm reset credentials flow.

aliases: resetCredentialsFlow
reset_password_allowed
boolean
    Choices:
  • no
  • yes
The realm reset password allowed option.

aliases: resetPasswordAllowed
revoke_refresh_token
boolean
    Choices:
  • no
  • yes
The realm revoke refresh token option.

aliases: revokeRefreshToken
smtp_server
dictionary
The realm smtp server.

aliases: smtpServer
ssl_required
string
    Choices:
  • all
  • external
  • none
The realm ssl required option.

aliases: sslRequired
sso_session_idle_timeout
integer
The realm sso session idle timeout.

aliases: ssoSessionIdleTimeout
sso_session_idle_timeout_remember_me
integer
The realm sso session idle timeout remember me.

aliases: ssoSessionIdleTimeoutRememberMe
sso_session_max_lifespan
integer
The realm sso session max lifespan.

aliases: ssoSessionMaxLifespan
sso_session_max_lifespan_remember_me
integer
The realm sso session max lifespan remember me.

aliases: ssoSessionMaxLifespanRememberMe
state
string
    Choices:
  • present ←
  • absent
State of the realm.
On present, the realm will be created (or updated if it exists already).
On absent, the realm will be removed if it exists.
supported_locales
list / elements=string
The realm supported locales.

aliases: supportedLocales
token
string
added in 3.0.0 of community.general
Authentication token for Keycloak API.
user_managed_access_allowed
boolean
    Choices:
  • no
  • yes
The realm user managed access allowed option.

aliases: userManagedAccessAllowed
validate_certs
boolean
    Choices:
  • no
  • yes ←
Verify TLS certificates (do not disable this in production).
verify_email
boolean
    Choices:
  • no
  • yes
The realm verify email option.

aliases: verifyEmail
wait_increment_seconds
integer
The realm wait increment in seconds.

aliases: waitIncrementSeconds

Examples

- name: Create or update Keycloak realm (minimal example)
  community.general.keycloak_realm:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    id: realm
    state: present

- name: Delete a Keycloak realm
  community.general.keycloak_realm:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    id: test
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
end_state
dictionary
on success
Representation of realm after module execution (sample is truncated).

Sample:
{'adminUrl': 'http://www.example.com/admin_url', 'attributes': {'request.object.signature.alg': 'RS256'}}
existing
dictionary
always
Representation of existing realm (sample is truncated).

Sample:
{'adminUrl': 'http://www.example.com/admin_url', 'attributes': {'request.object.signature.alg': 'RS256'}}
msg
string
always
Message as to what action was taken.

Sample:
Realm testrealm has been updated
proposed
dictionary
always
Representation of proposed realm.

Sample:
{'id': 'test'}


Authors

  • Christophe Gilles (@kris2kris)