authentication_v2: Fix validation for form-flows and client-flows

This commit is contained in:
Nils Bergmann
2026-09-09 10:36:56 +02:00
parent 8d5526aeb6
commit 638f694120
12 changed files with 440 additions and 21 deletions
@@ -0,0 +1,28 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
# Rebuilds Keycloak's own built-in "clients" flow structure as of 26.7.1.
# validate_executions() used to raise a KeyError for client-flow parents, since only
# basic-flow and form-flow provider sets were known.
- name: Flow Creation/Update <Integration Test Flow - Client Flow>
middleware_automation.keycloak.keycloak_authentication_v2:
realm: "{{ target_realm }}"
alias: Integration Test Flow - Client Flow
providerId: client-flow
state: present
authenticationExecutions:
- providerId: client-secret
requirement: ALTERNATIVE
- providerId: client-jwt
requirement: ALTERNATIVE
- providerId: client-secret-jwt
requirement: ALTERNATIVE
- providerId: client-x509
requirement: ALTERNATIVE
register: flow_v2_client_flow_result
- name: Expose flow_v2_client_flow_result to parent scope
ansible.builtin.set_fact:
flow_v2_client_flow_result: "{{ flow_v2_client_flow_result }}"
no_log: true
@@ -0,0 +1,31 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
# Rebuilds Keycloak's own built-in "registration" flow structure as of 26.7.1.
# validate_executions() used to only check authenticator-providers and falsely flagged form actions as invalid
# See https://github.com/ansible-middleware/keycloak/issues/382
- name: Flow Creation/Update <Integration Test Flow - Form Actions>
middleware_automation.keycloak.keycloak_authentication_v2:
realm: "{{ target_realm }}"
alias: Integration Test Flow - Form Actions
state: present
authenticationExecutions:
- subFlow: Integration Test Flow - Form Actions - registration form
subFlowType: form-flow
requirement: REQUIRED
authenticationExecutions:
- providerId: registration-user-creation
requirement: REQUIRED
- providerId: registration-password-action
requirement: REQUIRED
- providerId: registration-recaptcha-action
requirement: DISABLED
- providerId: registration-terms-and-conditions
requirement: DISABLED
register: flow_v2_form_action_result
- name: Expose flow_v2_form_action_result to parent scope
ansible.builtin.set_fact:
flow_v2_form_action_result: "{{ flow_v2_form_action_result }}"
no_log: true
@@ -0,0 +1,80 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
- name: Retrieve access token
ansible.builtin.include_tasks:
file: ../actions/fetch_access_token.yml
- name: Fetch all authentication flows
ansible.builtin.uri:
url: "{{ auth_keycloak_url }}/admin/realms/{{ target_realm }}/authentication/flows"
method: GET
headers:
Accept: application/json
User-agent: Ansible
Authorization: "Bearer {{ access_token }}"
return_content: true
register: keycloak_flows_response
no_log: true
- name: Extract flow id for alias 'Integration Test Flow - Client Flow'
ansible.builtin.set_fact:
test_flow_id: >-
{{ keycloak_flows_response.json
| selectattr('alias', 'equalto', 'Integration Test Flow - Client Flow')
| map(attribute='id')
| first }}
no_log: true
- name: Fetch basic flow data for 'Integration Test Flow - Client Flow'
ansible.builtin.uri:
url: "{{ auth_keycloak_url }}/admin/realms/{{ target_realm }}/authentication/flows/{{ test_flow_id }}"
method: GET
headers:
Accept: application/json
User-agent: Ansible
Authorization: "Bearer {{ access_token }}"
return_content: true
register: test_flow_top_level_data
no_log: true
- name: Assert flow attributes
ansible.builtin.assert:
that:
- test_flow_top_level_data.json.alias == "Integration Test Flow - Client Flow"
- test_flow_top_level_data.json.providerId == "client-flow"
- test_flow_top_level_data.json.topLevel == true
- test_flow_top_level_data.json.builtIn == false
- name: Fetch flow executions for 'Integration Test Flow - Client Flow'
ansible.builtin.uri:
url: "{{ auth_keycloak_url }}/admin/realms/{{ target_realm }}/authentication/flows/Integration%20Test%20Flow%20-%20Client%20Flow/executions"
method: GET
headers:
Accept: application/json
User-agent: Ansible
Authorization: "Bearer {{ access_token }}"
return_content: true
register: test_flow_executions
no_log: true
- name: Assert flow executions
ansible.builtin.assert:
that:
- test_flow_executions.json | length == 4
- test_flow_executions.json[0].providerId == "client-secret"
- test_flow_executions.json[0].requirement == "ALTERNATIVE"
- test_flow_executions.json[0].index == 0
- test_flow_executions.json[0].level == 0
- test_flow_executions.json[1].providerId == "client-jwt"
- test_flow_executions.json[1].requirement == "ALTERNATIVE"
- test_flow_executions.json[1].index == 1
- test_flow_executions.json[1].level == 0
- test_flow_executions.json[2].providerId == "client-secret-jwt"
- test_flow_executions.json[2].requirement == "ALTERNATIVE"
- test_flow_executions.json[2].index == 2
- test_flow_executions.json[2].level == 0
- test_flow_executions.json[3].providerId == "client-x509"
- test_flow_executions.json[3].requirement == "ALTERNATIVE"
- test_flow_executions.json[3].index == 3
- test_flow_executions.json[3].level == 0
@@ -0,0 +1,86 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
- name: Retrieve access token
ansible.builtin.include_tasks:
file: ../actions/fetch_access_token.yml
- name: Fetch all authentication flows
ansible.builtin.uri:
url: "{{ auth_keycloak_url }}/admin/realms/{{ target_realm }}/authentication/flows"
method: GET
headers:
Accept: application/json
User-agent: Ansible
Authorization: "Bearer {{ access_token }}"
return_content: true
register: keycloak_flows_response
no_log: true
- name: Extract flow id for alias 'Integration Test Flow - Form Actions'
ansible.builtin.set_fact:
test_flow_id: >-
{{ keycloak_flows_response.json
| selectattr('alias', 'equalto', 'Integration Test Flow - Form Actions')
| map(attribute='id')
| first }}
no_log: true
- name: Fetch basic flow data for 'Integration Test Flow - Form Actions'
ansible.builtin.uri:
url: "{{ auth_keycloak_url }}/admin/realms/{{ target_realm }}/authentication/flows/{{ test_flow_id }}"
method: GET
headers:
Accept: application/json
User-agent: Ansible
Authorization: "Bearer {{ access_token }}"
return_content: true
register: test_flow_top_level_data
no_log: true
- name: Assert flow attributes
ansible.builtin.assert:
that:
- test_flow_top_level_data.json.alias == "Integration Test Flow - Form Actions"
- test_flow_top_level_data.json.providerId == "basic-flow"
- test_flow_top_level_data.json.topLevel == true
- test_flow_top_level_data.json.builtIn == false
- name: Fetch flow executions for 'Integration Test Flow - Form Actions'
ansible.builtin.uri:
url: "{{ auth_keycloak_url }}/admin/realms/{{ target_realm }}/authentication/flows/Integration%20Test%20Flow%20-%20Form%20Actions/executions"
method: GET
headers:
Accept: application/json
User-agent: Ansible
Authorization: "Bearer {{ access_token }}"
return_content: true
register: test_flow_executions
no_log: true
- name: Assert flow executions
ansible.builtin.assert:
that:
- test_flow_executions.json | length == 5
- test_flow_executions.json[0].displayName == "Integration Test Flow - Form Actions - registration form"
- test_flow_executions.json[0].requirement == "REQUIRED"
- test_flow_executions.json[0].index == 0
- test_flow_executions.json[0].level == 0
- test_flow_executions.json[0].authenticationFlow == true
- test_flow_executions.json[1].providerId == "registration-user-creation"
- test_flow_executions.json[1].requirement == "REQUIRED"
- test_flow_executions.json[1].index == 0
- test_flow_executions.json[1].level == 1
- test_flow_executions.json[1]['authenticationFlow'] is not defined or test_flow_executions.json[1].authenticationFlow == false
- test_flow_executions.json[2].providerId == "registration-password-action"
- test_flow_executions.json[2].requirement == "REQUIRED"
- test_flow_executions.json[2].index == 1
- test_flow_executions.json[2].level == 1
- test_flow_executions.json[3].providerId == "registration-recaptcha-action"
- test_flow_executions.json[3].requirement == "DISABLED"
- test_flow_executions.json[3].index == 2
- test_flow_executions.json[3].level == 1
- test_flow_executions.json[4].providerId == "registration-terms-and-conditions"
- test_flow_executions.json[4].requirement == "DISABLED"
- test_flow_executions.json[4].index == 3
- test_flow_executions.json[4].level == 1
@@ -0,0 +1,33 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
- name: Setup Test
ansible.builtin.include_tasks:
file: test_setup.yml
- name: Create the new flow <Integration Test Flow - Client Flow>
ansible.builtin.include_tasks:
file: ../actions/flow_v2_client_flow.yml
- name: Assert the flow creation result
ansible.builtin.assert:
that:
- flow_v2_client_flow_result is changed
- flow_v2_client_flow_result.diff is defined
msg: "Expected changes and a diff but got: changed={{ flow_v2_client_flow_result.changed }}, diff={{ flow_v2_client_flow_result.get('diff') }}"
- name: Assert the created flow <Integration Test Flow - Client Flow>
ansible.builtin.include_tasks:
file: ../assertions/assertion_flow_v2_client_flow.yml
# Check idempotency, by trying to create the existing flow again
- name: Trying to create the <Integration Test Flow - Client Flow> again, although nothing changed
ansible.builtin.include_tasks:
file: ../actions/flow_v2_client_flow.yml
- name: Assert that the task didn't re-create the flow, because the flow didn't change
ansible.builtin.assert:
that:
- flow_v2_client_flow_result is not changed
- flow_v2_client_flow_result.diff is not defined
msg: "Expected no changes and no diff but got: changed={{ flow_v2_client_flow_result.changed }}, diff={{ flow_v2_client_flow_result.get('diff') }}"
@@ -0,0 +1,33 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
- name: Setup Test
ansible.builtin.include_tasks:
file: test_setup.yml
- name: Create the new flow <Integration Test Flow - Form Actions>
ansible.builtin.include_tasks:
file: ../actions/flow_v2_form_action.yml
- name: Assert the flow creation result
ansible.builtin.assert:
that:
- flow_v2_form_action_result is changed
- flow_v2_form_action_result.diff is defined
msg: "Expected changes and a diff but got: changed={{ flow_v2_form_action_result.changed }}, diff={{ flow_v2_form_action_result.get('diff') }}"
- name: Assert the created flow <Integration Test Flow - Form Actions>
ansible.builtin.include_tasks:
file: ../assertions/assertion_flow_v2_form_action.yml
# Check idempotency, by trying to create the existing flow again
- name: Trying to create the <Integration Test Flow - Form Actions> again, although nothing changed
ansible.builtin.include_tasks:
file: ../actions/flow_v2_form_action.yml
- name: Assert that the task didn't re-create the flow, because the flow didn't change
ansible.builtin.assert:
that:
- flow_v2_form_action_result is not changed
- flow_v2_form_action_result.diff is not defined
msg: "Expected no changes and no diff but got: changed={{ flow_v2_form_action_result.changed }}, diff={{ flow_v2_form_action_result.get('diff') }}"
@@ -39,7 +39,7 @@
- invalid_providerid_in_flow_result is failed
- invalid_providerid_in_flow_result is not changed
- >-
invalid_providerid_in_flow_result.msg == "Validation of executions failed: The following execution providerIds are unknown and therefore invalid: 'invalid-providerid', 'another-invalid-providerid'"
invalid_providerid_in_flow_result.msg == "Validation of executions failed: Error(s) while validating flow: Unknown providerId 'invalid-providerid', Unknown providerId 'another-invalid-providerid'"
- name: Retrieve access token
ansible.builtin.include_tasks:
@@ -0,0 +1,50 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
- name: Setup Test
ansible.builtin.include_tasks:
file: test_setup.yml
# form-action providers are valid for form-flow, but not for basic-flow.
# This test ensures that validate_executions() correctly rejects them when used in a basic-flow context.
# Same for authentication providers (e.g auth-cookie) in a form-flow context.
- name: Flow Creation/Update <Integration Test Flow - Mismatched Flow Type> with providerIds mismatched to their parent flow type
middleware_automation.keycloak.keycloak_authentication_v2:
realm: "{{ target_realm }}"
alias: Integration Test Flow - Mismatched Flow Type
state: present
authenticationExecutions:
- providerId: registration-user-creation
requirement: REQUIRED
- subFlow: Integration Test Flow - Mismatched Flow Type - form
subFlowType: form-flow
requirement: REQUIRED
authenticationExecutions:
- providerId: auth-cookie
requirement: REQUIRED
ignore_errors: true
register: mismatched_flow_type_result
- name: Assert providerIds mismatched with their parent flow type are rejected
ansible.builtin.assert:
that:
- mismatched_flow_type_result is failed
- mismatched_flow_type_result is not changed
- "'registration-user-creation' in mismatched_flow_type_result.msg"
- "'auth-cookie' in mismatched_flow_type_result.msg"
- name: Retrieve access token
ansible.builtin.include_tasks:
file: ../actions/fetch_access_token.yml
- name: Assert that the flow did not get created
ansible.builtin.uri:
url: "{{ auth_keycloak_url }}/admin/realms/{{ target_realm }}/authentication/flows/Integration%20Test%20Flow%20-%20Mismatched%20Flow%20Type/executions"
method: GET
headers:
Accept: application/json
User-agent: Ansible
Authorization: "Bearer {{ access_token }}"
return_content: true
status_code: 404
register: flow_response
@@ -24,4 +24,22 @@
middleware_automation.keycloak.keycloak_authentication_v2:
realm: "{{ target_realm }}"
alias: Integration Test Flow
state: absent
- name: Delete <Integration Test Flow - Form Actions> flow if it exists
middleware_automation.keycloak.keycloak_authentication_v2:
realm: "{{ target_realm }}"
alias: Integration Test Flow - Form Actions
state: absent
- name: Delete <Integration Test Flow - Mismatched Flow Type> flow if it exists
middleware_automation.keycloak.keycloak_authentication_v2:
realm: "{{ target_realm }}"
alias: Integration Test Flow - Mismatched Flow Type
state: absent
- name: Delete <Integration Test Flow - Client Flow> flow if it exists
middleware_automation.keycloak.keycloak_authentication_v2:
realm: "{{ target_realm }}"
alias: Integration Test Flow - Client Flow
state: absent
@@ -24,4 +24,16 @@
- name: Invalid providerIds in execution tests
ansible.builtin.include_tasks:
file: tests/test_invalid_providerid_flow_creation.yml
file: tests/test_invalid_providerid_flow_creation.yml
- name: Executing form action flow creation tests
ansible.builtin.include_tasks:
file: tests/test_form_action_flow_creation.yml
- name: Mismatched flow type providerIds in execution tests
ansible.builtin.include_tasks:
file: tests/test_mismatched_flow_type_flow_creation.yml
- name: Executing client flow creation tests
ansible.builtin.include_tasks:
file: tests/test_client_flow_creation.yml
@@ -109,6 +109,8 @@ URL_REALM_GROUP_ROLEMAPPINGS = "{url}/admin/realms/{realm}/groups/{group}/role-m
URL_CLIENTSECRET = "{url}/admin/realms/{realm}/clients/{id}/client-secret"
URL_AUTHENTICATION_AUTHENTICATOR_PROVIDERS = "{url}/admin/realms/{realm}/authentication/authenticator-providers"
URL_AUTHENTICATION_CLIENT_AUTHENTICATOR_PROVIDERS = "{url}/admin/realms/{realm}/authentication/client-authenticator-providers"
URL_AUTHENTICATION_FORM_ACTION_PROVIDERS = "{url}/admin/realms/{realm}/authentication/form-action-providers"
URL_AUTHENTICATION_FLOWS = "{url}/admin/realms/{realm}/authentication/flows"
URL_AUTHENTICATION_FLOW = "{url}/admin/realms/{realm}/authentication/flows/{id}"
URL_AUTHENTICATION_FLOW_COPY = "{url}/admin/realms/{realm}/authentication/flows/{copyfrom}/copy"
@@ -2294,6 +2296,32 @@ class KeycloakAPI:
except Exception as e:
self.fail_request(e, msg=f"Unable get authenticator providers in realm {realm}: {e}")
def get_client_authenticator_providers(self, realm: str = "master"):
"""
Get all available client authenticator providers of the realm.
:param realm: Realm.
:return: List of client authenticator provider representations.
"""
try:
return self._request_and_deserialize(
URL_AUTHENTICATION_CLIENT_AUTHENTICATOR_PROVIDERS.format(url=self.baseurl, realm=realm), method="GET"
)
except Exception as e:
self.fail_request(e, msg=f"Unable get client authenticator providers in realm {realm}: {e}")
def get_form_action_providers(self, realm: str = "master"):
"""
Get all available form action providers of the realm.
:param realm: Realm.
:return: List of form action provider representations.
"""
try:
return self._request_and_deserialize(
URL_AUTHENTICATION_FORM_ACTION_PROVIDERS.format(url=self.baseurl, realm=realm), method="GET"
)
except Exception as e:
self.fail_request(e, msg=f"Unable get form action providers in realm {realm}: {e}")
def get_authentication_flow_by_alias(self, alias, realm: str = "master"):
"""
Get an authentication flow by its alias
+39 -19
View File
@@ -519,6 +519,7 @@ extends_documentation_fragment:
author:
- Thomas Bargetz (@thomasbargetz)
- Nils Bergmann (@NilsBergmann)
"""
EXAMPLES = r"""
@@ -868,6 +869,12 @@ def existing_auth_to_diff_repr(kc: KeycloakAPI, realm: str, existing_auth: dict)
execution.pop("description", None)
execution.pop("flowId", None)
if execution.get("authenticationFlow"):
# This is always None for non-form-flows and defaults to 'registration-page-form' for form-flows.
# Keycloak supports custom form-flow providers via the FormAuthenticatorFactory SPI, but this module has no
# option to choose one, so the providerId is stripped from the existing execution before comparison.
execution.pop("providerId", None)
if execution.get("authenticationConfig") is not None:
execution["authenticationConfig"].pop("id", None)
# The alias is already stored inside the authenticationConfig object; the
@@ -1052,33 +1059,46 @@ def create_authentication_execution_spec_options(depth: int) -> dict[str, t.Any]
return options
def validate_executions(kc: KeycloakAPI, realm: str, executions: dict) -> None:
valid_providers = kc.get_authenticator_providers(realm)
valid_provider_ids = {provider["id"] for provider in valid_providers}
def validate_executions(kc: KeycloakAPI, realm: str, executions: dict, flow_type: str) -> None:
valid_provider_ids_by_flow_type = {
"basic-flow": {provider["id"] for provider in kc.get_authenticator_providers(realm)},
"form-flow": {provider["id"] for provider in kc.get_form_action_providers(realm)},
"client-flow": {provider["id"] for provider in kc.get_client_authenticator_providers(realm)},
}
all_known_provider_ids = set().union(*valid_provider_ids_by_flow_type.values())
invalid_provider_ids = validate_executions_rec(valid_provider_ids, executions)
if len(invalid_provider_ids) > 0:
invalid_provider_ids_str = ", ".join(f"'{item}'" for item in invalid_provider_ids)
raise ValueError(
f"The following execution providerIds are unknown and therefore invalid: {invalid_provider_ids_str}"
)
messages = []
has_issues = validate_executions_rec(valid_provider_ids_by_flow_type, all_known_provider_ids, executions, flow_type, messages)
if has_issues:
raise ValueError("Error(s) while validating flow: " + ", ".join(messages))
def validate_executions_rec(valid_provider_ids: set, executions: dict) -> list:
invalid_provider_ids = []
def validate_executions_rec(
valid_provider_ids_by_flow_type: dict, all_known_provider_ids: set, executions: dict, flow_type: str, messages: list
) -> bool:
if flow_type not in valid_provider_ids_by_flow_type:
messages.append(f"Unsupported flow type '{flow_type}'")
return True
has_issues = False
valid_provider_ids = valid_provider_ids_by_flow_type[flow_type]
for execution in executions:
provider_id = execution["providerId"]
sub_flow = execution.get("subFlow")
if provider_id is not None:
if provider_id not in valid_provider_ids:
invalid_provider_ids.append(provider_id)
if provider_id is not None and provider_id not in valid_provider_ids:
has_issues = True
if provider_id in all_known_provider_ids:
messages.append(f"'{provider_id}' is not a valid provider for parent flow '{flow_type}'")
else:
messages.append(f"Unknown providerId '{provider_id}'")
if sub_flow is not None:
invalid_provider_ids.extend(
validate_executions_rec(valid_provider_ids, execution["authenticationExecutions"])
)
if validate_executions_rec(
valid_provider_ids_by_flow_type, all_known_provider_ids, execution["authenticationExecutions"], execution["subFlowType"], messages
):
has_issues = True
return invalid_provider_ids
return has_issues
def main() -> None:
@@ -1141,7 +1161,7 @@ def main() -> None:
try:
try:
validate_executions(kc, realm, desired_auth["authenticationExecutions"])
validate_executions(kc, realm, desired_auth["authenticationExecutions"], desired_auth["providerId"])
except ValueError as e:
module.fail_json(
msg=f"Validation of executions failed: {e}",