community.general.keycloak_realm module – Allows administration of Keycloak realm 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_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
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)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication