Files
ansible-middleware.keycloak/main/_sources/plugins/keycloak_authentication_flow.rst.txt
ansible-middleware-core b0bedfc363 Update docs for main
Signed-off-by: ansible-middleware-core <ansible-middleware-core@redhat.com>
2026-06-01 14:26:22 +00:00

677 lines
26 KiB
ReStructuredText

.. Document meta
:orphan:
.. |antsibull-internal-nbsp| unicode:: 0xA0
:trim:
.. meta::
:antsibull-docs: 2.24.0
.. Anchors
.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_flow_module:
.. Anchors: short name for ansible.builtin
.. Title
keycloak_authentication_flow -- Allows administration of Keycloak authentication flows via Keycloak API
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. Collection note
.. note::
This module is part of the `middleware_automation.keycloak collection <https://galaxy.ansible.com/ui/repo/published/middleware_automation/keycloak/>`_.
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_flow`.
.. 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 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.
.. Aliases
.. Requirements
.. Options
Parameters
----------
.. raw:: html
<table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
<thead>
<tr class="row-odd">
<th class="head"><p>Parameter</p></th>
<th class="head"><p>Comments</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-alias"></div>
<p class="ansible-option-title"><strong>alias</strong></p>
<a class="ansibleOptionLink" href="#parameter-alias" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
/ <span class="ansible-option-required">required</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Alias (name) of the authentication flow.</p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-auth_client_id"></div>
<p class="ansible-option-title"><strong>auth_client_id</strong></p>
<a class="ansibleOptionLink" href="#parameter-auth_client_id" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>OpenID Connect <em>client_id</em> to authenticate to the API with.</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;admin-cli&#34;</code></p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-auth_client_secret"></div>
<p class="ansible-option-title"><strong>auth_client_secret</strong></p>
<a class="ansibleOptionLink" href="#parameter-auth_client_secret" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Client Secret to use in conjunction with <em>auth_client_id</em> (if required).</p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-auth_keycloak_url"></div>
<div class="ansibleOptionAnchor" id="parameter-url"></div>
<p class="ansible-option-title"><strong>auth_keycloak_url</strong></p>
<a class="ansibleOptionLink" href="#parameter-auth_keycloak_url" title="Permalink to this option"></a>
<p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: url</span></p>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
/ <span class="ansible-option-required">required</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>URL to the Keycloak instance.</p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-auth_password"></div>
<div class="ansibleOptionAnchor" id="parameter-password"></div>
<p class="ansible-option-title"><strong>auth_password</strong></p>
<a class="ansibleOptionLink" href="#parameter-auth_password" title="Permalink to this option"></a>
<p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: password</span></p>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Password to authenticate for API access with.</p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-auth_realm"></div>
<p class="ansible-option-title"><strong>auth_realm</strong></p>
<a class="ansibleOptionLink" href="#parameter-auth_realm" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Keycloak realm name to authenticate to for API access.</p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-auth_username"></div>
<div class="ansibleOptionAnchor" id="parameter-username"></div>
<p class="ansible-option-title"><strong>auth_username</strong></p>
<a class="ansibleOptionLink" href="#parameter-auth_username" title="Permalink to this option"></a>
<p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: username</span></p>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Username to authenticate for API access with.</p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-connection_timeout"></div>
<p class="ansible-option-title"><strong>connection_timeout</strong></p>
<a class="ansibleOptionLink" href="#parameter-connection_timeout" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">integer</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Controls the HTTP connections timeout period (in seconds) to Keycloak API.</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">10</code></p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-copy_from"></div>
<div class="ansibleOptionAnchor" id="parameter-copyFrom"></div>
<p class="ansible-option-title"><strong>copy_from</strong></p>
<a class="ansibleOptionLink" href="#parameter-copy_from" title="Permalink to this option"></a>
<p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: copyFrom</span></p>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>If set, the new flow is created as a copy of the flow with this alias.</p>
<p>Cannot be used together with <code class="ansible-option literal notranslate"><strong><a class="reference internal" href="#parameter-executions"><span class="std std-ref"><span class="pre">executions</span></span></a></strong></code>.</p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-description"></div>
<p class="ansible-option-title"><strong>description</strong></p>
<a class="ansibleOptionLink" href="#parameter-description" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Description of the authentication flow.</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;&#34;</code></p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-executions"></div>
<p class="ansible-option-title"><strong>executions</strong></p>
<a class="ansibleOptionLink" href="#parameter-executions" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">list</span>
/ <span class="ansible-option-elements">elements=dictionary</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>A list of executions (authenticator steps) to add to the flow.</p>
<p>Each execution is a dict with keys <code class='docutils literal notranslate'>provider_id</code> (or <code class='docutils literal notranslate'>providerId</code>) and <code class='docutils literal notranslate'>requirement</code>.</p>
<p>Executions are only added when the flow is first created.</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">[]</code></p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-executions/provider_id"></div>
<div class="ansibleOptionAnchor" id="parameter-executions/providerId"></div>
<p class="ansible-option-title"><strong>provider_id</strong></p>
<a class="ansibleOptionLink" href="#parameter-executions/provider_id" title="Permalink to this option"></a>
<p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: providerId</span></p>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
/ <span class="ansible-option-required">required</span>
</p>
</div></td>
<td><div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
<p>The authenticator provider ID (e.g. <code class="ansible-value literal notranslate">auth-cookie</code>, <code class="ansible-value literal notranslate">auth-password</code>, <code class="ansible-value literal notranslate">auth-otp-form</code>).</p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-executions/requirement"></div>
<p class="ansible-option-title"><strong>requirement</strong></p>
<a class="ansibleOptionLink" href="#parameter-executions/requirement" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
/ <span class="ansible-option-required">required</span>
</p>
</div></td>
<td><div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
<p>The requirement level for this execution.</p>
<p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
<ul class="simple">
<li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;REQUIRED&#34;</code></p></li>
<li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;ALTERNATIVE&#34;</code></p></li>
<li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;DISABLED&#34;</code></p></li>
<li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;CONDITIONAL&#34;</code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-http_agent"></div>
<p class="ansible-option-title"><strong>http_agent</strong></p>
<a class="ansibleOptionLink" href="#parameter-http_agent" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Configures the HTTP User-Agent header.</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;Ansible&#34;</code></p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-provider_id"></div>
<div class="ansibleOptionAnchor" id="parameter-providerId"></div>
<p class="ansible-option-title"><strong>provider_id</strong></p>
<a class="ansibleOptionLink" href="#parameter-provider_id" title="Permalink to this option"></a>
<p class="ansible-option-type-line"><span class="ansible-option-aliases">aliases: providerId</span></p>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>The provider ID for the flow.</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;basic-flow&#34;</code></p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-realm"></div>
<p class="ansible-option-title"><strong>realm</strong></p>
<a class="ansibleOptionLink" href="#parameter-realm" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>The Keycloak realm under which this authentication flow resides.</p>
<p class="ansible-option-line"><strong class="ansible-option-default-bold">Default:</strong> <code class="ansible-value literal notranslate ansible-option-default">&#34;master&#34;</code></p>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-refresh_token"></div>
<p class="ansible-option-title"><strong>refresh_token</strong></p>
<a class="ansibleOptionLink" href="#parameter-refresh_token" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Authentication refresh token for Keycloak API.</p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-state"></div>
<p class="ansible-option-title"><strong>state</strong></p>
<a class="ansibleOptionLink" href="#parameter-state" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>State of the authentication flow.</p>
<p>On <code class="ansible-value literal notranslate">present</code>, the flow will be created if it does not yet exist.</p>
<p>On <code class="ansible-value literal notranslate">absent</code>, the flow will be removed if it exists.</p>
<p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
<ul class="simple">
<li><p><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>&#34;present&#34;</strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;absent&#34;</code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-token"></div>
<p class="ansible-option-title"><strong>token</strong></p>
<a class="ansibleOptionLink" href="#parameter-token" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Authentication token for Keycloak API.</p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-validate_certs"></div>
<p class="ansible-option-title"><strong>validate_certs</strong></p>
<a class="ansibleOptionLink" href="#parameter-validate_certs" title="Permalink to this option"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">boolean</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Verify TLS certificates (do not disable this in production).</p>
<p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
<ul class="simple">
<li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">false</code></p></li>
<li><p><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>true</strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
</ul>
</div></td>
</tr>
</tbody>
</table>
.. 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
<div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="attribute-action_group"></div>
.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_flow_module__attribute-action_group:
.. rst-class:: ansible-option-title
**action_group**
.. raw:: html
<a class="ansibleOptionLink" href="#attribute-action_group" title="Permalink to this attribute"></a>
.. raw:: html
</div>
- .. raw:: html
<div class="ansible-option-cell">
:ansible-attribute-support-property:`Action group:` |antsibull-internal-nbsp|:ansible-attribute-support-full:`middleware\_automation.keycloak.keycloak`
.. raw:: html
</div>
- .. raw:: html
<div class="ansible-option-cell">
Use :literal:`group/middleware\_automation.keycloak.keycloak` in :literal:`module\_defaults` to set defaults for this module.
.. raw:: html
</div>
* - .. raw:: html
<div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="attribute-check_mode"></div>
.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_flow_module__attribute-check_mode:
.. rst-class:: ansible-option-title
**check_mode**
.. raw:: html
<a class="ansibleOptionLink" href="#attribute-check_mode" title="Permalink to this attribute"></a>
.. raw:: html
</div>
- .. raw:: html
<div class="ansible-option-cell">
:ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full`
.. raw:: html
</div>
- .. raw:: html
<div class="ansible-option-cell">
Can run in :literal:`check\_mode` and return changed status prediction without modifying target.
.. raw:: html
</div>
* - .. raw:: html
<div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="attribute-diff_mode"></div>
.. _ansible_collections.middleware_automation.keycloak.keycloak_authentication_flow_module__attribute-diff_mode:
.. rst-class:: ansible-option-title
**diff_mode**
.. raw:: html
<a class="ansibleOptionLink" href="#attribute-diff_mode" title="Permalink to this attribute"></a>
.. raw:: html
</div>
- .. raw:: html
<div class="ansible-option-cell">
:ansible-attribute-support-label:`Support: \ `\ :ansible-attribute-support-full:`full`
.. raw:: html
</div>
- .. raw:: html
<div class="ansible-option-cell">
Will return details on what has changed (or possibly needs changing in :literal:`check\_mode`\ ), when in diff mode.
.. raw:: html
</div>
.. Notes
.. Seealso
.. Examples
Examples
--------
.. code-block:: yaml+jinja
- 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
.. Facts
.. Return values
Return Values
-------------
Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this module:
.. raw:: html
<table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
<thead>
<tr class="row-odd">
<th class="head"><p>Key</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="return-end_state"></div>
<p class="ansible-option-title"><strong>end_state</strong></p>
<a class="ansibleOptionLink" href="#return-end_state" title="Permalink to this return value"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">dictionary</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Representation of the authentication flow after module execution.</p>
<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> on success</p>
<p class="ansible-option-line ansible-option-sample"><strong class="ansible-option-sample-bold">Sample:</strong> <code class="ansible-value literal notranslate ansible-option-sample">{&#34;alias&#34;: &#34;my-browser-flow&#34;, &#34;builtIn&#34;: false, &#34;id&#34;: &#34;uuid-here&#34;, &#34;providerId&#34;: &#34;basic-flow&#34;, &#34;topLevel&#34;: true}</code></p>
</div></td>
</tr>
<tr class="row-odd">
<td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="return-msg"></div>
<p class="ansible-option-title"><strong>msg</strong></p>
<a class="ansibleOptionLink" href="#return-msg" title="Permalink to this return value"></a>
<p class="ansible-option-type-line">
<span class="ansible-option-type">string</span>
</p>
</div></td>
<td><div class="ansible-option-cell">
<p>Message as to what action was taken.</p>
<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> always</p>
<p class="ansible-option-line ansible-option-sample"><strong class="ansible-option-sample-bold">Sample:</strong> <code class="ansible-value literal notranslate ansible-option-sample">&#34;Authentication flow my-browser-flow has been created&#34;</code></p>
</div></td>
</tr>
</tbody>
</table>
.. Status (Presently only deprecated)
.. Authors
Authors
~~~~~~~
- Paulo Menon (@paulomenon)
.. Extra links
.. Parsing errors