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.5.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_authentication_v2.

New in community.general 12.5.0

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}

Authors

  • Thomas Bargetz (@thomasbargetz)