community.general.keycloak_authentication_v2 module – Configure authentication flows in Keycloak in an idempotent and safe manner.

Note

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

New in community.general 12.5.0

Synopsis
Parameters
Attributes
Examples
Return Values

Synopsis

This module allows the creation, deletion, and modification of Keycloak authentication flows using the Keycloak REST API.
Rather than modifying an existing flow in place, the module re-creates the flow using the Safe Swap mechanism described below.
Safe Swap mechanism - When an authentication flow needs to be updated, the module never modifies the existing flow in place. Instead it follows a multi-step swap procedure to ensure the flow is never left in an intermediate or unsafe state during the update. This is especially important when the flow is actively bound to a realm binding, a client override, or as an identity-provider login-flow or post-flow, because a partially-updated flow could inadvertently allow unauthorised access.
The Safe Swap mechanism is as follows. 1. A new flow is created under a temporary name (the original alias plus a configurable suffix, for example myflow_tmp_for_swap). 2. All executions and their configurations are added to the new temporary flow. 3. If the existing flow is currently bound to a realm or a client, all bindings are redirected to the new temporary flow. This ensures continuity and avoids any gap in active authentication coverage. 4. The old flow is deleted. 5. The temporary flow is renamed to the original alias, restoring the expected name.
Handling pre-existing temporary swap flows - If a temporary swap flow already exists (for example, from a previously interrupted run), the module can optionally delete it before proceeding. This behaviour is controlled by the force_temporary_swap_flow_deletion option. If the option is false and a temporary flow already exists, the module will fail to prevent accidental data loss.
Idempotency - If the existing flow already matches the desired configuration, no changes are made. The module compares a normalised representation of the existing flow against the desired state before deciding whether to trigger the Safe Swap procedure.
A depth of 4 sub-flows is supported.

Parameters

Parameter	Comments
alias string / required	The name of the authentication flow.
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.
authenticationExecutions list / elements=dictionary	The desired execution configuration for the flow. Executions at root level.
authenticationConfig dictionary	The configuration for the execution.
alias string / required	Name of the execution config.
config dictionary / required	Options for the execution config.
authenticationExecutions list / elements=dictionary	The execution configuration for executions within the sub-flow. Executions at sub level 1.
authenticationConfig dictionary	The configuration for the execution.
alias string / required	Name of the execution config.
config dictionary / required	Options for the execution config.
authenticationExecutions list / elements=dictionary	The execution configuration for executions within the sub-flow. Executions at sub level 2.
authenticationConfig dictionary	The configuration for the execution.
alias string / required	Name of the execution config.
config dictionary / required	Options for the execution config.
authenticationExecutions list / elements=dictionary	The execution configuration for executions within the sub-flow. Executions at sub level 3.
authenticationConfig dictionary	The configuration for the execution.
alias string / required	Name of the execution config.
config dictionary / required	Options for the execution config.
authenticationExecutions list / elements=dictionary	The execution configuration for executions within the sub-flow. Executions at sub level 4 (last sub level).
authenticationConfig dictionary	The configuration for the execution.
alias string / required	Name of the execution config.
config dictionary / required	Options for the execution config.
providerId string / required	The `providerId` of the execution.
requirement string / required	The requirement status of the execution or sub-flow. Choices: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
providerId string	The `providerId` of the execution.
requirement string / required	The requirement status of the execution or sub-flow. Choices: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	The name of the sub-flow.
subFlowType string	The type of the sub-flow. Choices: `"basic-flow"` ← (default) `"form-flow"`
providerId string	The `providerId` of the execution.
requirement string / required	The requirement status of the execution or sub-flow. Choices: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	The name of the sub-flow.
subFlowType string	The type of the sub-flow. Choices: `"basic-flow"` ← (default) `"form-flow"`
providerId string	The `providerId` of the execution.
requirement string / required	The requirement status of the execution or sub-flow. Choices: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	The name of the sub-flow.
subFlowType string	The type of the sub-flow. Choices: `"basic-flow"` ← (default) `"form-flow"`
providerId string	The `providerId` of the execution.
requirement string / required	The requirement status of the execution or sub-flow. Choices: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	The name of the sub-flow.
subFlowType string	The type of the sub-flow. Choices: `"basic-flow"` ← (default) `"form-flow"`
connection_timeout integer added in community.general 4.5.0	Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: `10`
description string	A human-readable description of the flow.
force_temporary_swap_flow_deletion boolean	If `true`, any pre-existing temporary swap flow (identified by the original alias plus `temporary_swap_flow_suffix`) is deleted before the Safe Swap procedure begins. Set this to `false` to cause the module to fail instead of silently removing a pre-existing temporary flow, for example to avoid accidental data loss after an interrupted run. Choices: `false` `true` ← (default)
http_agent string added in community.general 5.4.0	Configures the HTTP User-Agent header. Default: `"Ansible"`
providerId string	The `providerId` for the new flow. Choices: `"basic-flow"` ← (default) `"client-flow"`
realm string / required	The name of the realm in which the authentication flow resides.
refresh_token string added in community.general 10.3.0	Authentication refresh token for Keycloak API.
state string	Whether the authentication flow should exist or not. Choices: `"present"` ← (default) `"absent"`
temporary_swap_flow_suffix string	The suffix appended to the alias of the temporary flow created during a Safe Swap update. The temporary flow exists only for the duration of the swap procedure and is renamed to the original alias once all bindings have been successfully transferred. Default: `"_tmp_for_swap"`
token string added in community.general 3.0.0	Authentication token for Keycloak API.
validate_certs boolean	Verify TLS certificates (do not disable this in production). Choices: `false` `true` ← (default)

Attributes

Attribute	Support	Description
action_group	Action group: community.general.keycloak	Use `group/community.general.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	Returns details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Examples

- name: Create or modify the 'My Login Flow'.
  community.general.keycloak_authentication_v2:
    auth_keycloak_url: http://localhost:8080/auth
    auth_realm: master
    auth_username: admin
    auth_password: password
    realm: master
    alias: My Login Flow
    authenticationExecutions:
      - providerId: idp-review-profile
        requirement: REQUIRED
        authenticationConfig:
          alias: My Login Flow - review profile config
          config:
            update.profile.on.first.login: "missing"
      - subFlow: My Login Flow - User creation or linking
        requirement: REQUIRED
        authenticationExecutions:
          - providerId: idp-create-user-if-unique
            requirement: ALTERNATIVE
            authenticationConfig:
              alias: My Login Flow - create unique user config
              config:
                require.password.update.after.registration: "true"
          - providerId: auth-cookie
            requirement: REQUIRED
          - subFlow: My Login Flow - Handle Existing Account
            requirement: ALTERNATIVE
            authenticationExecutions:
              - providerId: idp-confirm-link
                requirement: REQUIRED
      - providerId: auth-cookie
        requirement: DISABLED
    state: present

- name: Remove an authentication flow.
  community.general.keycloak_authentication_v2:
    auth_keycloak_url: http://localhost:8080/auth
    auth_realm: master
    auth_username: admin
    auth_password: password
    realm: master
    alias: My Login Flow
    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 the authentication flow after module execution. Returned: on success Sample: {"alias": "My Login Flow", "authenticationExecutions": [{"alias": "review profile config", "authenticationConfig": {"alias": "review profile config", "config": {"update.profile.on.first.login": "missing"}, "id": "6f09e4fb-aad4-496a-b873-7fa9779df6d7"}, "configurable": true, "displayName": "Review Profile", "id": "8f77dab8-2008-416f-989e-88b09ccf0b4c", "index": 0, "level": 0, "providerId": "idp-review-profile", "requirement": "REQUIRED", "requirementChoices": ["REQUIRED", "ALTERNATIVE", "DISABLED"]}], "builtIn": false, "description": "Actions taken after first broker login with identity provider account, which is not yet linked to any Keycloak account", "id": "bc228863-5887-4297-b898-4d988f8eaa5c", "providerId": "basic-flow", "topLevel": true}

Key

Description

end_state

dictionary

Representation of the authentication flow after module execution.

Returned: on success

Sample: {"alias": "My Login Flow", "authenticationExecutions": [{"alias": "review profile config", "authenticationConfig": {"alias": "review profile config", "config": {"update.profile.on.first.login": "missing"}, "id": "6f09e4fb-aad4-496a-b873-7fa9779df6d7"}, "configurable": true, "displayName": "Review Profile", "id": "8f77dab8-2008-416f-989e-88b09ccf0b4c", "index": 0, "level": 0, "providerId": "idp-review-profile", "requirement": "REQUIRED", "requirementChoices": ["REQUIRED", "ALTERNATIVE", "DISABLED"]}], "builtIn": false, "description": "Actions taken after first broker login with identity provider account, which is not yet linked to any Keycloak account", "id": "bc228863-5887-4297-b898-4d988f8eaa5c", "providerId": "basic-flow", "topLevel": true}

Authors

Thomas Bargetz (@thomasbargetz)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/general/keycloak_authentication_v2_module.html