.. Document meta :orphan: .. |antsibull-internal-nbsp| unicode:: 0xA0 :trim: .. meta:: :antsibull-docs: 2.24.0 .. Anchors .. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module: .. Anchors: short name for ansible.builtin .. Title keycloak_authentication_v2 -- Configure authentication flows in Keycloak in an idempotent and safe manner. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. Collection note .. 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 :code:`ansible-galaxy collection list`. To install it, use: :code:`ansible\-galaxy collection install middleware\_automation.keycloak`. To use it in a playbook, specify: :code:`middleware_automation.keycloak.keycloak_authentication_v2`. .. version_added .. rst-class:: ansible-version-added New in middleware\_automation.keycloak 3.0.0 .. contents:: :local: :depth: 1 .. Deprecated Synopsis -------- .. Description - 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 :strong:`Safe Swap` mechanism described below. - :strong:`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 :strong:`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 :literal:`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. - :strong:`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 :ansopt:`middleware\_automation.keycloak.keycloak\_authentication\_v2#module:force\_temporary\_swap\_flow\_deletion` option. If the option is :ansval:`false` and a temporary flow already exists, the module will fail to prevent accidental data loss. - :strong:`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. .. Aliases .. Requirements .. Options Parameters ---------- .. raw:: html

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 Attributes ---------- .. tabularcolumns:: \X{2}{10}\X{3}{10}\X{5}{10} .. list-table:: :width: 100% :widths: auto :header-rows: 1 :class: longtable ansible-option-table * - Attribute - Support - Description * - .. raw:: html
.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module__attribute-action_group: .. rst-class:: ansible-option-title **action_group** .. raw:: html .. raw:: html
- .. raw:: html
:ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak` .. raw:: html
- .. raw:: html
Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module. .. raw:: html
* - .. raw:: html
.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module__attribute-check_mode: .. rst-class:: ansible-option-title **check_mode** .. raw:: html .. raw:: html
- .. raw:: html
:ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` .. raw:: html
- .. raw:: html
Can run in :literal:`check\_mode` and return changed status prediction without modifying target. .. raw:: html
* - .. raw:: html
.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_v2_module__attribute-diff_mode: .. rst-class:: ansible-option-title **diff_mode** .. raw:: html .. raw:: html
- .. raw:: html
:ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full` .. raw:: html
- .. raw:: html
Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode. .. raw:: html
.. Notes .. Seealso .. Examples Examples -------- .. code-block:: yaml+jinja - 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 .. Facts .. Return values Return Values ------------- Common return values are documented :ref:`here `, the following are the fields unique to this module: .. raw:: html

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}
.. Status (Presently only deprecated) .. Authors Authors ~~~~~~~ - Thomas Bargetz (@thomasbargetz) .. Extra links .. Parsing errors