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

Note

This module is part of the community.general collection (version 10.1.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 community.general 3.0.0

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

Comments

access_code_lifespan

aliases: accessCodeLifespan

integer

The realm access code lifespan.

access_code_lifespan_login

aliases: accessCodeLifespanLogin

integer

The realm access code lifespan login.

access_code_lifespan_user_action

aliases: accessCodeLifespanUserAction

integer

The realm access code lifespan user action.

access_token_lifespan

aliases: accessTokenLifespan

integer

The realm access token lifespan.

access_token_lifespan_for_implicit_flow

aliases: accessTokenLifespanForImplicitFlow

integer

The realm access token lifespan for implicit flow.

account_theme

aliases: accountTheme

string

The realm account theme.

action_token_generated_by_admin_lifespan

aliases: actionTokenGeneratedByAdminLifespan

integer

The realm action token generated by admin lifespan.

action_token_generated_by_user_lifespan

aliases: actionTokenGeneratedByUserLifespan

integer

The realm action token generated by user lifespan.

admin_events_details_enabled

aliases: adminEventsDetailsEnabled

boolean

The realm admin events details enabled.

Choices:

  • false

  • true

admin_events_enabled

aliases: adminEventsEnabled

boolean

The realm admin events enabled.

Choices:

  • false

  • true

admin_theme

aliases: adminTheme

string

The realm admin theme.

attributes

dictionary

The realm attributes.

auth_client_id

string

OpenID Connect client_id to authenticate to the API with.

Default: "admin-cli"

auth_client_secret

string

Client Secret to use in conjunction with auth_client_id (if required).

auth_keycloak_url

aliases: url

string / required

URL to the Keycloak instance.

auth_password

aliases: password

string

Password to authenticate for API access with.

auth_realm

string

Keycloak realm name to authenticate to for API access.

auth_username

aliases: username

string

Username to authenticate for API access with.

browser_flow

aliases: browserFlow

string

The realm browser flow.

browser_security_headers

aliases: browserSecurityHeaders

dictionary

The realm browser security headers.

brute_force_protected

aliases: bruteForceProtected

boolean

The realm brute force protected.

Choices:

  • false

  • true

client_authentication_flow

aliases: clientAuthenticationFlow

string

The realm client authentication flow.

client_scope_mappings

aliases: clientScopeMappings

dictionary

The realm client scope mappings.

connection_timeout

integer

added in community.general 4.5.0

Controls the HTTP connections timeout period (in seconds) to Keycloak API.

Default: 10

default_default_client_scopes

aliases: defaultDefaultClientScopes

list / elements=string

The realm default default client scopes.

default_groups

aliases: defaultGroups

list / elements=string

The realm default groups.

default_locale

aliases: defaultLocale

string

The realm default locale.

default_optional_client_scopes

aliases: defaultOptionalClientScopes

list / elements=string

The realm default optional client scopes.

default_roles

aliases: defaultRoles

list / elements=string

The realm default roles.

default_signature_algorithm

aliases: defaultSignatureAlgorithm

string

The realm default signature algorithm.

direct_grant_flow

aliases: directGrantFlow

string

The realm direct grant flow.

display_name

aliases: displayName

string

The realm display name.

display_name_html

aliases: displayNameHtml

string

The realm display name HTML.

docker_authentication_flow

aliases: dockerAuthenticationFlow

string

The realm docker authentication flow.

duplicate_emails_allowed

aliases: duplicateEmailsAllowed

boolean

The realm duplicate emails allowed option.

Choices:

  • false

  • true

edit_username_allowed

aliases: editUsernameAllowed

boolean

The realm edit username allowed option.

Choices:

  • false

  • true

email_theme

aliases: emailTheme

string

The realm email theme.

enabled

boolean

The realm enabled option.

Choices:

  • false

  • true

enabled_event_types

aliases: enabledEventTypes

list / elements=string

The realm enabled event types.

events_enabled

aliases: eventsEnabled

boolean

added in community.general 3.6.0

Enables or disables login events for this realm.

Choices:

  • false

  • true

events_expiration

aliases: eventsExpiration

integer

The realm events expiration.

events_listeners

aliases: eventsListeners

list / elements=string

The realm events listeners.

failure_factor

aliases: failureFactor

integer

The realm failure factor.

http_agent

string

added in community.general 5.4.0

Configures the HTTP User-Agent header.

Default: "Ansible"

id

string

The realm to create.

internationalization_enabled

aliases: internationalizationEnabled

boolean

The realm internationalization enabled option.

Choices:

  • false

  • true

login_theme

aliases: loginTheme

string

The realm login theme.

login_with_email_allowed

aliases: loginWithEmailAllowed

boolean

The realm login with email allowed option.

Choices:

  • false

  • true

max_delta_time_seconds

aliases: maxDeltaTimeSeconds

integer

The realm max delta time in seconds.

max_failure_wait_seconds

aliases: maxFailureWaitSeconds

integer

The realm max failure wait in seconds.

minimum_quick_login_wait_seconds

aliases: minimumQuickLoginWaitSeconds

integer

The realm minimum quick login wait in seconds.

not_before

aliases: notBefore

integer

The realm not before.

offline_session_idle_timeout

aliases: offlineSessionIdleTimeout

integer

The realm offline session idle timeout.

offline_session_max_lifespan

aliases: offlineSessionMaxLifespan

integer

The realm offline session max lifespan.

offline_session_max_lifespan_enabled

aliases: offlineSessionMaxLifespanEnabled

boolean

The realm offline session max lifespan enabled option.

Choices:

  • false

  • true

organizations_enabled

aliases: organizationsEnabled

boolean

added in community.general 10.0.0

Enables support for experimental organization feature.

Choices:

  • false

  • true

otp_policy_algorithm

aliases: otpPolicyAlgorithm

string

The realm otp policy algorithm.

otp_policy_digits

aliases: otpPolicyDigits

integer

The realm otp policy digits.

otp_policy_initial_counter

aliases: otpPolicyInitialCounter

integer

The realm otp policy initial counter.

otp_policy_look_ahead_window

aliases: otpPolicyLookAheadWindow

integer

The realm otp policy look ahead window.

otp_policy_period

aliases: otpPolicyPeriod

integer

The realm otp policy period.

otp_policy_type

aliases: otpPolicyType

string

The realm otp policy type.

otp_supported_applications

aliases: otpSupportedApplications

list / elements=string

The realm otp supported applications.

password_policy

aliases: passwordPolicy

string

The realm password policy.

permanent_lockout

aliases: permanentLockout

boolean

The realm permanent lockout.

Choices:

  • false

  • true

quick_login_check_milli_seconds

aliases: quickLoginCheckMilliSeconds

integer

The realm quick login check in milliseconds.

realm

string

The realm name.

refresh_token_max_reuse

aliases: refreshTokenMaxReuse

integer

The realm refresh token max reuse.

registration_allowed

aliases: registrationAllowed

boolean

The realm registration allowed option.

Choices:

  • false

  • true

registration_email_as_username

aliases: registrationEmailAsUsername

boolean

The realm registration email as username option.

Choices:

  • false

  • true

registration_flow

aliases: registrationFlow

string

The realm registration flow.

remember_me

aliases: rememberMe

boolean

The realm remember me option.

Choices:

  • false

  • true

reset_credentials_flow

aliases: resetCredentialsFlow

string

The realm reset credentials flow.

reset_password_allowed

aliases: resetPasswordAllowed

boolean

The realm reset password allowed option.

Choices:

  • false

  • true

revoke_refresh_token

aliases: revokeRefreshToken

boolean

The realm revoke refresh token option.

Choices:

  • false

  • true

smtp_server

aliases: smtpServer

dictionary

The realm smtp server.

ssl_required

aliases: sslRequired

string

The realm ssl required option.

Choices:

  • "all"

  • "external"

  • "none"

sso_session_idle_timeout

aliases: ssoSessionIdleTimeout

integer

The realm sso session idle timeout.

sso_session_idle_timeout_remember_me

aliases: ssoSessionIdleTimeoutRememberMe

integer

The realm sso session idle timeout remember me.

sso_session_max_lifespan

aliases: ssoSessionMaxLifespan

integer

The realm sso session max lifespan.

sso_session_max_lifespan_remember_me

aliases: ssoSessionMaxLifespanRememberMe

integer

The realm sso session max lifespan remember me.

state

string

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.

Choices:

  • "present" ← (default)

  • "absent"

supported_locales

aliases: supportedLocales

list / elements=string

The realm supported locales.

token

string

added in community.general 3.0.0

Authentication token for Keycloak API.

user_managed_access_allowed

aliases: userManagedAccessAllowed

boolean

The realm user managed access allowed option.

Choices:

  • false

  • true

validate_certs

boolean

Verify TLS certificates (do not disable this in production).

Choices:

  • false

  • true ← (default)

verify_email

aliases: verifyEmail

boolean

The realm verify email option.

Choices:

  • false

  • true

wait_increment_seconds

aliases: waitIncrementSeconds

integer

The realm wait increment in seconds.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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
    realm: 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

Description

end_state

dictionary

Representation of realm after module execution (sample is truncated).

Returned: on success

Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

existing

dictionary

Representation of existing realm (sample is truncated).

Returned: always

Sample: {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

msg

string

Message as to what action was taken.

Returned: always

Sample: "Realm testrealm has been updated"

proposed

dictionary

Representation of proposed realm.

Returned: always

Sample: {"id": "test"}

Authors

  • Christophe Gilles (@kris2kris)