Spec-Zone.ru › Ansible

Модуль community.general.keycloak_realm_key — управление ключами realm Keycloak с помощью API Keycloak

Примечание

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

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

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

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

Добавлено в community.general 7.5.0

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

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

  • Этот модуль позволяет управлять ключами realm Keycloak с помощью REST API Keycloak. Для него необходим доступ к REST API через OpenID Connect; подключающийся пользователь и используемый realm должны иметь необходимые права доступа. В конфигурации Keycloak по умолчанию подойдут admin-cli и пользователь-администратор, как и отдельное определение realm с областью действия, настроенной в соответствии с вашими потребностями, и пользователем с необходимыми ролями.
  • Названия параметров модуля представляют собой версии в snake_case названий в camelCase, используемых в API Keycloak и его документации по адресу https://www.keycloak.org/docs-api/8.0/rest-api/index.html. Предусмотрены псевдонимы, поэтому можно использовать и варианты в camelCase.
  • Этот модуль не может обнаружить изменения самого криптографического ключа после его импорта. Однако, если одновременно с криптографическим ключом изменяется какое-либо другое свойство, ключ также изменится как побочный эффект, поскольку полезная нагрузка JSON должна содержать закрытый ключ. Это можно считать как ошибкой, так и особенностью, поскольку альтернативой было бы всегда обновлять ключ realm вне зависимости от того, изменился он или нет.

Параметры

Параметр

Комментарии

auth_client_id

string

OpenID Connect client_id для аутентификации в 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.

config

dictionary

Словарь с указанием ключа и его свойств.

active

boolean

Активен или неактивен ли ключ. Не следует путать с состоянием ресурса Ansible, управляемого параметром state.

Варианты:

  • false
  • true ← (по умолчанию)

algorithm

string

Алгоритм ключа.

Значения RS384, RS512, PS256, PS384, PS512, RSA1_5, RSA-OAEP, RSA-OAEP-256 добавлены в community.general 8.2.0.

Значения HS256, HS384, HS512 (для HMAC), ES256, ES384, ES512 (для ECDSA) и AES добавлены в community.general 12.4.0.

Значения ECDH_ES, ECDH_ES_A128KW, ECDH_ES_A192KW, ECDH_ES_A256KW (для обмена ключами ECDH), а также Ed25519, Ed448 (для подписи EdDSA) добавлены в community.general 12.4.0.

Для provider_id=rsa, provider_id=rsa-generated и provider_id=java-keystore по умолчанию используется RS256.

Для provider_id=rsa-enc и provider_id=rsa-enc-generated должно быть указано одно из значений RSA1_5, RSA-OAEP, RSA-OAEP-256 (обязательный параметр, без значения по умолчанию).

Для provider_id=hmac-generated должно быть указано одно из значений HS256, HS384, HS512 (обязательный параметр, без значения по умолчанию).

Для provider_id=ecdsa-generated должно быть указано одно из значений ES256, ES384, ES512 (обязательный параметр, без значения по умолчанию).

Для provider_id=ecdh-generated должно быть указано одно из значений ECDH_ES, ECDH_ES_A128KW, ECDH_ES_A192KW, ECDH_ES_A256KW (обязательный параметр, без значения по умолчанию).

Для provider_id=eddsa-generated этот параметр не используется (алгоритм определяется параметром config.elliptic_curve).

Для provider_id=aes-generated этот параметр не используется (всегда используется AES).

Варианты:

  • "RS256" ← (по умолчанию)
  • "RS384"
  • "RS512"
  • "PS256"
  • "PS384"
  • "PS512"
  • "RSA1_5"
  • "RSA-OAEP"
  • "RSA-OAEP-256"
  • "HS256"
  • "HS384"
  • "HS512"
  • "ES256"
  • "ES384"
  • "ES512"
  • "AES"
  • "ECDH_ES"
  • "ECDH_ES_A128KW"
  • "ECDH_ES_A192KW"
  • "ECDH_ES_A256KW"
  • "Ed25519"
  • "Ed448"

certificate

string

Сертификат, подписанный закрытым ключом, в виде строки ASCII. Содержимое ключа должно соответствовать config.algorithm и provider_id.

Чтобы Keycloak автоматически создал сертификат с помощью закрытого ключа, задайте пустую строку.

Обязателен, если provider_id равен rsa или rsa-enc. Не используется для автоматически создаваемых провайдеров.

elliptic_curve

string

добавлено в community.general 12.4.0

Эллиптическая кривая для ключей ECDSA, ECDH или EdDSA.

Для provider_id=ecdsa-generated и provider_id=ecdh-generated допустимы значения P-256, P-384, P-521. По умолчанию используется P-256.

Для provider_id=eddsa-generated допустимы значения Ed25519, Ed448. По умолчанию используется Ed25519.

Варианты:

  • "P-256"
  • "P-384"
  • "P-521"
  • "Ed25519"
  • "Ed448"

enabled

boolean

Включён или отключён ли ключ. Не следует путать с состоянием ресурса Ansible, управляемого параметром state.

Варианты:

  • false
  • true ← (по умолчанию)

key_alias

string

добавлено в community.general 12.4.0

Псевдоним ключа в хранилище ключей.

Обязателен, если provider_id=java-keystore.

key_password

string

добавлено в community.general 12.4.0

Пароль ключа в хранилище ключей.

Если не указан, используется config.keystore_password.

Применяется только к provider_id=java-keystore.

key_size

integer

добавлено в community.general 12.4.0

Размер создаваемого ключа в битах.

Применяется только к provider_id=rsa-generated и provider_id=rsa-enc-generated.

Допустимые значения: 1024, 2048, 4096. По умолчанию используется 2048.

keystore

string

добавлено в community.general 12.4.0

Путь к файлу Java Keystore в файловой системе сервера Keycloak.

Обязателен, если provider_id=java-keystore.

keystore_password

string

добавлено в community.general 12.4.0

Пароль Java Keystore.

Обязателен, если provider_id=java-keystore.

priority

integer / обязательный

Приоритет ключа.

private_key

string

Закрытый ключ в виде строки ASCII. Содержимое ключа должно соответствовать config.algorithm и provider_id.

Обратите внимание: модуль не может определить, отличается ли указанный закрытый ключ от закрытого ключа в текущем состоянии. Используйте force=true, чтобы принудительно обновить закрытый ключ, если ожидаете, что он будет обновлён.

Обязателен, если provider_id равен rsa или rsa-enc. Не используется для автоматически создаваемых провайдеров.

secret_size

integer

добавлено в community.general 12.4.0

Размер создаваемого секретного ключа в байтах.

Применяется только к provider_id=hmac-generated и provider_id=aes-generated.

Допустимые значения: 16, 24, 32, 64, 128, 256, 512.

По умолчанию для HMAC используется 64, для AES — 16.

connection_timeout

integer

добавлено в community.general 4.5.0

Задаёт время ожидания HTTP-подключений к API Keycloak (в секундах).

По умолчанию: 10

force

boolean

Принудительно обеспечивает требуемое состояние закрытого ключа и сертификата. Это не происходит автоматически, поскольку модуль не может определить текущее состояние закрытого ключа и, следовательно, не может инициировать обновление на основе фактического расхождения. При этом обновление закрытого ключа может произойти как побочный эффект других изменений, даже если force имеет значение false.

Варианты:

  • false ← (по умолчанию)
  • true

http_agent

string

добавлено в community.general 5.4.0

Настраивает HTTP-заголовок User-Agent.

По умолчанию: "Ansible"

name

string / обязательный

Имя создаваемого ключа realm.

parent_id

string / обязательный

Значение parent_id ключа realm. На практике — имя realm.

provider_id

string

Название «идентификатора провайдера» для ключа.

Значение rsa-enc добавлено в community.general 8.2.0.

Значение java-keystore добавлено в community.general 12.4.0. Этот провайдер импортирует ключи из файла Java Keystore (JKS или PKCS12), расположенного в файловой системе сервера Keycloak.

Значения rsa-generated, hmac-generated, aes-generated и ecdsa-generated добавлены в community.general 12.4.0. Это провайдеры автоматически создаваемых ключей, материал ключей для которых управляется Keycloak.

Значения rsa-enc-generated, ecdh-generated и eddsa-generated добавлены в community.general 12.4.0. Они соответствуют провайдерам автоматически создаваемых ключей, доступным в Keycloak 26.

Варианты:

  • "rsa" ← (по умолчанию)
  • "rsa-enc"
  • "java-keystore"
  • "rsa-generated"
  • "rsa-enc-generated"
  • "hmac-generated"
  • "aes-generated"
  • "ecdsa-generated"
  • "ecdh-generated"
  • "eddsa-generated"

refresh_token

string

добавлено в community.general 10.3.0

Токен обновления аутентификации для API Keycloak.

state

string

Состояние ключа realm Keycloak.

При значении present ключ realm создаётся (или обновляется, если уже существует).

При значении absent ключ realm удаляется, если существует.

Варианты:

  • "present" ← (по умолчанию)
  • "absent"

token

string

добавлено в community.general 3.0.0

Токен аутентификации для API Keycloak.

update_password

string

добавлено в community.general 12.4.0

Определяет, когда пароли передаются в Keycloak для провайдера java-keystore.

always — всегда передавать пароли. Keycloak обновит компонент, даже если пароли не изменились. Используйте этот вариант, если необходимо обеспечить обновление паролей.

on_create — передавать пароли только при создании нового компонента. При обновлении существующего компонента передаётся замаскированное значение, чтобы сохранить текущие пароли. Благодаря этому поля паролей в модуле становятся идемпотентными.

Это необходимо, поскольку Keycloak маскирует пароли в ответах API (возвращает **********), что делает сравнение невозможным.

Не влияет на провайдеры, отличные от java-keystore.

Варианты:

  • "always" ← (по умолчанию)
  • "on_create"

validate_certs

boolean

Проверять TLS-сертификаты (не отключайте эту проверку в рабочей среде).

Варианты:

  • false
  • true ← (по умолчанию)

Атрибуты

Атрибут

Поддержка

Описание

action_group

Группа действий: community.general.keycloak

добавлено в community.general 10.2.0

Используйте group/community.general.keycloak в module_defaults, чтобы задать значения по умолчанию для этого модуля.

check_mode

Поддержка: полная

Может выполняться в режиме check_mode и возвращать прогноз изменения состояния, не изменяя целевой объект.

diff_mode

Поддержка: частичная

В режиме diff возвращает сведения об изменениях (или о том, что, возможно, необходимо изменить в check_mode).

Примечания

Примечание

  • Текущее значение закрытого ключа невозможно получить из Keycloak. Поэтому сравнить желаемое состояние с текущим нельзя.
  • Если config.certificate не задан явно, Keycloak создаёт его динамически. Поэтому сравнить текущее состояние сертификата с желаемым (которое может быть пустым) нельзя.
  • Из-за параметров закрытого ключа и сертификата модуль не является полностью идемпотентным. Можно использовать force=true, чтобы принудительно обеспечить обновление, если известно, что закрытый ключ мог измениться.
  • Для автоматически создаваемых провайдеров (rsa-generated, rsa-enc-generated, hmac-generated, aes-generated, ecdsa-generated, ecdh-generated, eddsa-generated) Keycloak автоматически управляет материалом ключей. Параметры config.private_key и config.certificate не используются.
  • Для провайдера java-keystore значения config.keystore_password и config.key_password возвращаются Keycloak в замаскированном виде. Поэтому сравнить их текущее состояние с желаемым нельзя. Используйте update_password=on_create для идемпотентных плейбуков или update_password=always (по умолчанию), если необходимо обеспечить обновление паролей.

Примеры

- name: Manage Keycloak realm key (certificate autogenerated by Keycloak)
  community.general.keycloak_realm_key:
    name: custom
    state: present
    parent_id: master
    provider_id: rsa
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      private_key: "{{ private_key }}"
      certificate: ""
      enabled: true
      active: true
      priority: 120
      algorithm: RS256

- name: Manage Keycloak realm key and certificate
  community.general.keycloak_realm_key:
    name: custom
    state: present
    parent_id: master
    provider_id: rsa
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      private_key: "{{ private_key }}"
      certificate: "{{ certificate }}"
      enabled: true
      active: true
      priority: 120
      algorithm: RS256

- name: Create HMAC signing key (auto-generated)
  community.general.keycloak_realm_key:
    name: hmac-custom
    state: present
    parent_id: master
    provider_id: hmac-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      enabled: true
      active: true
      priority: 100
      algorithm: HS256
      secret_size: 64

- name: Create AES encryption key (auto-generated)
  community.general.keycloak_realm_key:
    name: aes-custom
    state: present
    parent_id: master
    provider_id: aes-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      enabled: true
      active: true
      priority: 100
      secret_size: 16

- name: Create ECDSA signing key (auto-generated)
  community.general.keycloak_realm_key:
    name: ecdsa-custom
    state: present
    parent_id: master
    provider_id: ecdsa-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      enabled: true
      active: true
      priority: 100
      algorithm: ES256
      elliptic_curve: P-256

- name: Create RSA signing key (auto-generated)
  community.general.keycloak_realm_key:
    name: rsa-auto
    state: present
    parent_id: master
    provider_id: rsa-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      enabled: true
      active: true
      priority: 100
      algorithm: RS256
      key_size: 2048

- name: Remove default HMAC key
  community.general.keycloak_realm_key:
    name: hmac-generated
    state: absent
    parent_id: myrealm
    provider_id: hmac-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      priority: 100

- name: Create RSA encryption key (auto-generated)
  community.general.keycloak_realm_key:
    name: rsa-enc-auto
    state: present
    parent_id: master
    provider_id: rsa-enc-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      enabled: true
      active: true
      priority: 100
      algorithm: RSA-OAEP
      key_size: 2048

- name: Create ECDH key exchange key (auto-generated)
  community.general.keycloak_realm_key:
    name: ecdh-custom
    state: present
    parent_id: master
    provider_id: ecdh-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      enabled: true
      active: true
      priority: 100
      algorithm: ECDH_ES
      elliptic_curve: P-256

- name: Create EdDSA signing key (auto-generated)
  community.general.keycloak_realm_key:
    name: eddsa-custom
    state: present
    parent_id: master
    provider_id: eddsa-generated
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    config:
      enabled: true
      active: true
      priority: 100
      elliptic_curve: Ed25519

- name: Import key from Java Keystore (always update passwords)
  community.general.keycloak_realm_key:
    name: jks-imported
    state: present
    parent_id: master
    provider_id: java-keystore
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    # update_password: always is the default - passwords are always sent to Keycloak
    config:
      enabled: true
      active: true
      priority: 100
      algorithm: RS256
      keystore: /opt/keycloak/conf/keystore.jks
      keystore_password: "{{ keystore_password }}"
      key_alias: mykey
      key_password: "{{ key_password }}"

- name: Import key from Java Keystore (idempotent - only set password on create)
  community.general.keycloak_realm_key:
    name: jks-idempotent
    state: present
    parent_id: master
    provider_id: java-keystore
    auth_keycloak_url: http://localhost:8080/auth
    auth_username: keycloak
    auth_password: keycloak
    auth_realm: master
    update_password: on_create  # Only send passwords when creating, preserve existing on update
    config:
      enabled: true
      active: true
      priority: 100
      algorithm: RS256
      keystore: /opt/keycloak/conf/keystore.jks
      keystore_password: "{{ keystore_password }}"
      key_alias: mykey
      key_password: "{{ key_password }}"

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

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

Ключ

Описание

end_state

dictionary

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

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

config

dictionary

Конфигурация ключа области.

Возвращается: когда state=present

Пример: {"active": ["true"], "algorithm": ["RS256"], "enabled": ["true"], "priority": ["140"]}

id

string

ID ключа области.

Возвращается: когда state=present

Пример: "5b7ec13f-99da-46ad-8326-ab4c73cf4ce4"

key_info

dictionary

добавлено в community.general 12.4.0

Метаданные криптографического ключа, полученные из конечной точки ключей области.

Возвращается только для поставщика java-keystore, если state=present и не используется режим проверки.

Содержит идентификатор ключа (kid) и отпечаток сертификата, которые позволяют определить, изменился ли фактический криптографический ключ.

Возвращается: когда provider_id=java-keystore и state=present

certificate_fingerprint

string

Отпечаток SHA256 сертификата в шестнадцатеричном формате с разделителями-двокрапиями.

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

Пример: "A1:B2:C3:D4:E5:F6:..."

kid

string

Идентификатор ключа (kid) — уникальный идентификатор криптографического ключа.

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

Пример: "bN7p5Nc_V2M7N_-mb5vVSRVPKq5qD_OuARInB9ofsJ0"

status

string

Статус ключа (ACTIVE, PASSIVE, DISABLED).

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

Пример: "ACTIVE"

valid_to

integer

Время истечения срока действия сертификата в миллисекундах с начала эпохи.

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

Пример: 1801789047000

name

string

Имя ключа области.

Возвращается: когда state=present

Пример: "mykey"

parentId

string

ID области, которой принадлежит этот ключ.

Возвращается: когда state=present

Пример: "myrealm"

providerId

string

ID поставщика ключа.

Возвращается: когда state=present

Пример: "rsa"

providerType

string

Тип поставщика.

Возвращается: когда state=present

msg

string

Сообщение о выполненном действии.

Возвращается: всегда

Авторы

  • Samuli Seppänen (@mattock)
  • Ivan Kokalović (@koke1997)

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

  • Отслеживание проблем
  • Репозиторий (исходный код)
  • Запросить помощь
  • Сообщить об ошибке
  • Предложить функцию
  • Связь

© 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_realm_key_module.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API