Модуль community.general.keycloak_authentication_v2 — настройка потоков аутентификации в Keycloak идемпотентным и безопасным способом.

Примечание

Этот модуль входит в коллекцию community.general (версия 12.6.1).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните команду ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.general.

Чтобы использовать её в плейбуке, укажите: community.general.keycloak_authentication_v2.

Новое в community.general 12.5.0

Краткое описание
Параметры
Атрибуты
Примеры
Возвращаемые значения

Краткое описание

Этот модуль позволяет создавать, удалять и изменять потоки аутентификации Keycloak с помощью REST API Keycloak.
Вместо изменения существующего потока на месте модуль пересоздаёт его с помощью описанного ниже механизма безопасной замены.
Механизм безопасной замены — когда необходимо обновить поток аутентификации, модуль никогда не изменяет существующий поток на месте. Вместо этого он выполняет многоэтапную процедуру замены, чтобы во время обновления поток никогда не оставался в промежуточном или небезопасном состоянии. Это особенно важно, если поток активно привязан к привязке области, переопределению клиента или используется в качестве потока входа либо последующего потока поставщика удостоверений, поскольку частично обновлённый поток может непреднамеренно предоставить несанкционированный доступ.
Механизм безопасной замены работает следующим образом. 1. Создаётся новый поток с временным именем (исходный псевдоним плюс настраиваемый суффикс, например myflow_tmp_for_swap). 2. В новый временный поток добавляются все выполнения и их конфигурации. 3. Если существующий поток в данный момент привязан к области или клиенту, все привязки перенаправляются на новый временный поток. Это обеспечивает непрерывность и позволяет избежать разрыва активного покрытия аутентификацией. 4. Старый поток удаляется. 5. Временному потоку присваивается исходный псевдоним, восстанавливая ожидаемое имя.
Обработка ранее созданных временных потоков замены — если временный поток замены уже существует (например, после прерванного предыдущего запуска), модуль может при необходимости удалить его перед продолжением. Это поведение управляется параметром force_temporary_swap_flow_deletion. Если параметр имеет значение false и временный поток уже существует, модуль завершится с ошибкой, чтобы предотвратить случайную потерю данных.
Идемпотентность — если существующий поток уже соответствует требуемой конфигурации, изменения не вносятся. Перед тем как решить, следует ли запускать процедуру безопасной замены, модуль сравнивает нормализованное представление существующего потока с требуемым состоянием.
Поддерживается глубина вложенности до 4 подпотоков.

Параметры

Параметр	Комментарии
alias string / обязательный	Имя потока аутентификации.
auth_client_id string	`client_id` OpenID Connect для аутентификации в API. По умолчанию: `"admin-cli"`
auth_client_secret string	Секрет клиента, используемый вместе с `auth_client_id` (если требуется).
auth_keycloak_url псевдонимы: url string / обязательный	URL экземпляра Keycloak.
auth_password псевдонимы: password string	Пароль для аутентификации при доступе к API.
auth_realm string	Имя realm Keycloak для аутентификации при доступе к API.
auth_username псевдонимы: username string	Имя пользователя для аутентификации при доступе к API.
authenticationExecutions list / элементы=dictionary	Требуемая конфигурация выполнений для потока. Выполнения корневого уровня.
authenticationConfig dictionary	Конфигурация выполнения.
alias string / обязательный	Имя конфигурации выполнения.
config dictionary / обязательный	Параметры конфигурации выполнения.
authenticationExecutions list / элементы=dictionary	Конфигурация выполнений для выполнений внутри вложенного потока. Выполнения вложенного уровня 1.
authenticationConfig dictionary	Конфигурация выполнения.
alias string / обязательный	Имя конфигурации выполнения.
config dictionary / обязательный	Параметры конфигурации выполнения.
authenticationExecutions list / элементы=dictionary	Конфигурация выполнений для выполнений внутри вложенного потока. Выполнения вложенного уровня 2.
authenticationConfig dictionary	Конфигурация выполнения.
alias string / обязательный	Имя конфигурации выполнения.
config dictionary / обязательный	Параметры конфигурации выполнения.
authenticationExecutions list / элементы=dictionary	Конфигурация выполнений для выполнений внутри вложенного потока. Выполнения вложенного уровня 3.
authenticationConfig dictionary	Конфигурация выполнения.
alias string / обязательный	Имя конфигурации выполнения.
config dictionary / обязательный	Параметры конфигурации выполнения.
authenticationExecutions list / элементы=dictionary	Конфигурация выполнений для выполнений внутри вложенного потока. Выполнения вложенного уровня 4 (последний вложенный уровень).
authenticationConfig dictionary	Конфигурация выполнения.
alias string / обязательный	Имя конфигурации выполнения.
config dictionary / обязательный	Параметры конфигурации выполнения.
providerId string / обязательный	`providerId` выполнения.
requirement string / обязательный	Статус обязательности выполнения или вложенного потока. Варианты: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
providerId string	`providerId` выполнения.
requirement string / обязательный	Статус обязательности выполнения или вложенного потока. Варианты: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	Имя вложенного потока.
subFlowType string	Тип вложенного потока. Варианты: `"basic-flow"` ← (по умолчанию) `"form-flow"`
providerId string	`providerId` выполнения.
requirement string / обязательный	Статус обязательности выполнения или вложенного потока. Варианты: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	Имя вложенного потока.
subFlowType string	Тип вложенного потока. Варианты: `"basic-flow"` ← (по умолчанию) `"form-flow"`
providerId string	`providerId` выполнения.
requirement string / обязательный	Статус обязательности выполнения или вложенного потока. Варианты: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	Имя вложенного потока.
subFlowType string	Тип вложенного потока. Варианты: `"basic-flow"` ← (по умолчанию) `"form-flow"`
providerId string	`providerId` выполнения.
requirement string / обязательный	Статус обязательности выполнения или вложенного потока. Варианты: `"REQUIRED"` `"ALTERNATIVE"` `"DISABLED"` `"CONDITIONAL"`
subFlow string	Имя вложенного потока.
subFlowType string	Тип вложенного потока. Варианты: `"basic-flow"` ← (по умолчанию) `"form-flow"`
connection_timeout integer добавлено в community.general 4.5.0	Задает время ожидания HTTP-соединения с API Keycloak (в секундах). По умолчанию: `10`
description string	Понятное пользователю описание потока.
force_temporary_swap_flow_deletion boolean	Если `true`, любой ранее существовавший временный поток замены (определяемый по исходному псевдониму и `temporary_swap_flow_suffix`) удаляется до начала процедуры безопасной замены. Задайте `false`, чтобы модуль завершился с ошибкой вместо незаметного удаления ранее созданного временного потока, например, чтобы избежать случайной потери данных после прерванного запуска. Варианты: `false` `true` ← (по умолчанию)
http_agent string добавлено в community.general 5.4.0	Настраивает заголовок HTTP User-Agent. По умолчанию: `"Ansible"`
providerId string	`providerId` для нового потока. Варианты: `"basic-flow"` ← (по умолчанию) `"client-flow"`
realm string / обязательный	Имя realm, в котором находится поток аутентификации.
refresh_token string добавлено в community.general 10.3.0	Токен обновления аутентификации для API Keycloak.
state string	Должен ли поток аутентификации существовать. Варианты: `"present"` ← (по умолчанию) `"absent"`

temporary_swap_flow_suffix string	Суффикс, добавляемый к псевдониму временного потока, созданного во время обновления Safe Swap. Временный поток существует только во время процедуры подмены и переименовывается в исходный псевдоним после успешного переноса всех привязок. По умолчанию: `"_tmp_for_swap"`
token string добавлено в community.general 3.0.0	Токен аутентификации для API Keycloak.
validate_certs boolean	Проверять TLS-сертификаты (не отключайте эту проверку в рабочей среде). Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группа действий: community.general.keycloak	Используйте `group/community.general.keycloak` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: полная	Может выполняться в режиме `check_mode` и возвращать прогноз изменения статуса, не изменяя целевой объект.
diff_mode	Поддержка: полная	Возвращает сведения об изменениях (или возможных изменениях в `check_mode`) при работе в режиме сравнения.

Примеры

- name: Create or modify the 'My Login Flow'.
  community.general.keycloak_authentication_v2:
    auth_keycloak_url: http://localhost:8080/auth
    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.
  community.general.keycloak_authentication_v2:
    auth_keycloak_url: http://localhost:8080/auth
    auth_realm: master
    auth_username: admin
    auth_password: password
    realm: master
    alias: My Login Flow
    state: absent

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
end_state dictionary	Представление потока аутентификации после выполнения модуля. Возвращается: при успешном выполнении Пример: {"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}

Ключ

Описание

end_state

dictionary

Представление потока аутентификации после выполнения модуля.

Возвращается: при успешном выполнении

Пример: {"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}

Авторы

Thomas Bargetz (@thomasbargetz)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/general/keycloak_authentication_v2_module.html