# keycloak_realm – Allows administration of Keycloak realm via 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 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 middleware_automation.keycloak 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 middleware_automation.keycloak 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 middleware_automation.keycloak 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 middleware_automation.keycloak 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)
      middleware_automation.keycloak.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
      middleware_automation.keycloak.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)