# keycloak_authentication_v2 – Configure authentication flows in Keycloak in an idempotent and safe manner. — Keycloak Ansible Collection documentation

# keycloak_authentication_v2 – Configure authentication flows in Keycloak in an idempotent and safe manner.

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

New in middleware_automation.keycloak 3.0.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 | 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 | 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 | 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 | 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: middleware_automation.keycloak.keycloak | 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 modify the 'My Login Flow'.
      middleware_automation.keycloak.keycloak_authentication_v2:
        auth_keycloak_url: http://localhost:8080
        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.
      middleware_automation.keycloak.keycloak_authentication_v2:
        auth_keycloak_url: http://localhost:8080
        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)