# keycloak_authentication_flow – Allows administration of Keycloak authentication flows via Keycloak API — Keycloak Ansible Collection documentation

# keycloak_authentication_flow – Allows administration of Keycloak authentication flows 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_authentication_flow`.

New in middleware_automation.keycloak 3.0.0

## Synopsis

- This module allows you to add, remove or modify Keycloak authentication flows via the Keycloak REST API. It requires access to the REST API via OpenID Connect; the user connecting and the client 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 client definition with the scope tailored to your needs and a user having the expected roles.

- This module supports creating new top-level authentication flows, copying existing flows, and adding execution steps to a flow.

## Parameters

Parameter | Comments
--- | ---
alias string / required | Alias (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.
connection_timeout integer | Controls the HTTP connections timeout period (in seconds) to Keycloak API. Default: `10`
copy_from aliases: copyFrom string | If set, the new flow is created as a copy of the flow with this alias. Cannot be used together with `executions`.
description string | Description of the authentication flow. Default: `""`
executions list / elements=dictionary | A list of executions (authenticator steps) to add to the flow. Each execution is a dict with keys `provider_id` (or `providerId`) and `requirement`. Executions are only added when the flow is first created. Default: `[]`
provider_id aliases: providerId string / required | The authenticator provider ID (e.g. `auth-cookie`, `auth-password`, `auth-otp-form`).

requirement

string / required

The requirement level for this execution.

Choices:

- `"REQUIRED"`

- `"ALTERNATIVE"`

- `"DISABLED"`

- `"CONDITIONAL"`

http_agent string | Configures the HTTP User-Agent header. Default: `"Ansible"`
provider_id aliases: providerId string | The provider ID for the flow. Default: `"basic-flow"`
realm string | The Keycloak realm under which this authentication flow resides. Default: `"master"`
refresh_token string | Authentication refresh token for Keycloak API.

state

string

State of the authentication flow.

On `present`, the flow will be created if it does not yet exist.

On `absent`, the flow will be removed if it exists.

Choices:

- `"present"` ← (default)

- `"absent"`

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 an authentication flow with executions
      middleware_automation.keycloak.keycloak_authentication_flow:
        auth_keycloak_url: http://localhost:8080
        auth_realm: master
        auth_username: admin
        auth_password: password
        realm: TestRealm
        alias: my-browser-flow
        description: "Custom browser flow"
        provider_id: basic-flow
        executions:
          - provider_id: auth-cookie
            requirement: ALTERNATIVE
          - provider_id: auth-password
            requirement: REQUIRED
          - provider_id: auth-otp-form
            requirement: ALTERNATIVE
        state: present
      delegate_to: localhost

    - name: Create an authentication flow by copying an existing one
      middleware_automation.keycloak.keycloak_authentication_flow:
        auth_keycloak_url: http://localhost:8080
        auth_realm: master
        auth_username: admin
        auth_password: password
        realm: TestRealm
        alias: my-copy-of-browser
        copy_from: browser
        state: present
      delegate_to: localhost

    - name: Create a flow using token authentication
      middleware_automation.keycloak.keycloak_authentication_flow:
        auth_keycloak_url: http://localhost:8080
        token: MY_TOKEN
        realm: TestRealm
        alias: my-flow
        state: present
      delegate_to: localhost

    - name: Delete an authentication flow
      middleware_automation.keycloak.keycloak_authentication_flow:
        auth_keycloak_url: http://localhost:8080
        auth_realm: master
        auth_username: admin
        auth_password: password
        realm: TestRealm
        alias: my-browser-flow
        state: absent
      delegate_to: localhost

## 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-browser-flow", "builtIn": false, "id": "uuid-here", "providerId": "basic-flow", "topLevel": true}`
msg string | Message as to what action was taken. Returned: always Sample: `"Authentication flow my-browser-flow has been created"`

### Authors

- Paulo Menon (@paulomenon)