# keycloak_realm – Allows administration of Keycloak realm using Keycloak API — Keycloak Ansible Collection documentation

# keycloak_realm – Allows administration of Keycloak realm using Keycloak API

Note

This module is part of the middleware_automation.keycloak collection.

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 middleware_automation.keycloak`.

To use it in a playbook, specify: `middleware_automation.keycloak.keycloak_realm`.

New in middleware_automation.keycloak 3.0.0

## Synopsis

- This module allows the administration of Keycloak realm using the Keycloak REST API. It requires access to the REST API using 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/latest/rest-api/index.html. Aliases are provided so camelCased versions can be used as well.

- The Keycloak API does not always sanity check inputs, for example you can set SAML-specific settings on an OpenID Connect client for instance and also the other way around. 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_permissions_enabled

aliases: adminPermissionsEnabled

boolean

The realm admin permissions 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`

brute_force_strategy

aliases: bruteForceStrategy

string

The realm brute force strategy.

Choices:

- `"LINEAR"`

- `"MULTIPLE"`

client_authentication_flow aliases: clientAuthenticationFlow string | The realm client authentication flow.
client_offline_session_idle_timeout aliases: clientOfflineSessionIdleTimeout integer | All Clients inherit from this setting, time an offline session is allowed to be idle before it expires.
client_offline_session_max_lifespan aliases: clientOfflineSessionMaxLifespan integer | All Clients inherit from this setting, max time before an offline session is expired regardless of activity.
client_scope_mappings aliases: clientScopeMappings dictionary | The realm client scope mappings.
client_session_idle_timeout aliases: clientSessionIdleTimeout integer | All Clients inherit from this setting, time a session is allowed to be idle before it expires.
client_session_max_lifespan aliases: clientSessionMaxLifespan integer | All Clients inherit from this setting, max time before a session is expired.
connection_timeout integer | 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

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.
first_broker_login_flow aliases: firstBrokerLoginFlow string | The realm first broker login flow.
http_agent string | 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`

localization_texts aliases: localizationTexts dictionary | The custom localization texts for a realm.
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.
max_temporary_lockouts aliases: maxTemporaryLockouts integer | The realm max temporary lockouts.
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.
oauth2_device_code_lifespan aliases: oauth2DeviceCodeLifespan integer | Max time before the device code and user code are expired.
oauth2_device_polling_interval aliases: oauth2DevicePollingInterval integer | The minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.
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

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 string | Authentication refresh token for Keycloak API.
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 is created (or updated if it exists already).

On `absent`, the realm is removed if it exists.

Choices:

- `"present"` ← (default)

- `"absent"`

supported_locales aliases: supportedLocales list / elements=string | The realm supported locales.
token string | 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.
web_authn_policy_acceptable_aaguids aliases: webAuthnPolicyAcceptableAaguids list / elements=string | List of acceptable AAGUIDs for WebAuthn authenticators.
web_authn_policy_attestation_conveyance_preference aliases: webAuthnPolicyAttestationConveyancePreference string | Attestation conveyance preference for WebAuthn.
web_authn_policy_authenticator_attachment aliases: webAuthnPolicyAuthenticatorAttachment string | Authenticator attachment preference for WebAuthn authenticators.

web_authn_policy_avoid_same_authenticator_register

aliases: webAuthnPolicyAvoidSameAuthenticatorRegister

boolean

Avoid registering the same authenticator multiple times.

Choices:

- `false`

- `true`

web_authn_policy_create_timeout aliases: webAuthnPolicyCreateTimeout integer | Timeout for WebAuthn credential creation (ms).
web_authn_policy_extra_origins aliases: webAuthnPolicyExtraOrigins list / elements=string | Additional acceptable origins for WebAuthn requests.
web_authn_policy_passwordless_acceptable_aaguids aliases: webAuthnPolicyPasswordlessAcceptableAaguids list / elements=string | List of acceptable AAGUIDs for WebAuthn passwordless authenticators.
web_authn_policy_passwordless_attestation_conveyance_preference aliases: webAuthnPolicyPasswordlessAttestationConveyancePreference string | Attestation conveyance preference for WebAuthn passwordless.
web_authn_policy_passwordless_authenticator_attachment aliases: webAuthnPolicyPasswordlessAuthenticatorAttachment string | Authenticator attachment for WebAuthn passwordless.

web_authn_policy_passwordless_avoid_same_authenticator_register

aliases: webAuthnPolicyPasswordlessAvoidSameAuthenticatorRegister

boolean

Avoid registering the same authenticator multiple times for passwordless.

Choices:

- `false`

- `true`

web_authn_policy_passwordless_create_timeout aliases: webAuthnPolicyPasswordlessCreateTimeout integer | Timeout for WebAuthn passwordless credential creation (ms).
web_authn_policy_passwordless_extra_origins aliases: webAuthnPolicyPasswordlessExtraOrigins list / elements=string | Additional acceptable origins for WebAuthn passwordless requests.

web_authn_policy_passwordless_passkeys_enabled

aliases: webAuthnPolicyPasswordlessPasskeysEnabled

boolean

Enable passkeys (conditional UI) authentication in the username forms.

Choices:

- `false`

- `true`

web_authn_policy_passwordless_require_resident_key aliases: webAuthnPolicyPasswordlessRequireResidentKey string | Whether resident keys are required for WebAuthn passwordless (`Yes`/`No`/`not specified`).
web_authn_policy_passwordless_rp_entity_name aliases: webAuthnPolicyPasswordlessRpEntityName string | WebAuthn Passwordless Relying Party Entity Name.
web_authn_policy_passwordless_rp_id aliases: webAuthnPolicyPasswordlessRpId string | WebAuthn Passwordless Relying Party ID (domain).
web_authn_policy_passwordless_signature_algorithms aliases: webAuthnPolicyPasswordlessSignatureAlgorithms list / elements=string | List of acceptable WebAuthn signature algorithms for passwordless.
web_authn_policy_passwordless_user_verification_requirement aliases: webAuthnPolicyPasswordlessUserVerificationRequirement string | User verification requirement for WebAuthn passwordless.
web_authn_policy_require_resident_key aliases: webAuthnPolicyRequireResidentKey string | Whether resident keys are required for WebAuthn (Yes/No/not specified).
web_authn_policy_rp_entity_name aliases: webAuthnPolicyRpEntityName string | WebAuthn Relying Party Entity Name.
web_authn_policy_rp_id aliases: webAuthnPolicyRpId string | WebAuthn Relying Party ID (domain). Empty string means use request host.
web_authn_policy_signature_algorithms aliases: webAuthnPolicySignatureAlgorithms list / elements=string | List of acceptable WebAuthn signature algorithms.
web_authn_policy_user_verification_requirement aliases: webAuthnPolicyUserVerificationRequirement string | User verification requirement for WebAuthn.

## Attributes

Attribute | Support | Description
--- | --- | ---
action_group | Action group: middleware_automation.keycloak.keycloak added in middleware_automation.keycloak 3.0.0 | Use `group/middleware_automation.keycloak.keycloak` in `module_defaults` to set defaults for this module.
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)
      middleware_automation.keycloak.keycloak_realm:
        auth_client_id: admin-cli
        auth_keycloak_url: https://auth.example.com
        auth_realm: master
        auth_username: USERNAME
        auth_password: PASSWORD
        realm: unique_realm_name
        state: present

    - name: Delete a Keycloak realm
      middleware_automation.keycloak.keycloak_realm:
        auth_client_id: admin-cli
        auth_keycloak_url: https://auth.example.com
        auth_realm: master
        auth_username: USERNAME
        auth_password: PASSWORD
        realm: unique_realm_name
        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: `{"realm": "test"}`

### Authors

- Christophe Gilles (@kris2kris)