community.general.keycloak_realm_key 模块 – 通过 Keycloak API 管理 Keycloak realm 密钥

注意

此模块是 community.general 集合 (版本 10.1.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。

要在 playbook 中使用它，请指定：community.general.keycloak_realm_key。

community.general 7.5.0 中的新增功能

概要

• 此模块允许通过 Keycloak REST API 管理 Keycloak realm 密钥。它需要通过 OpenID Connect 访问 REST API；连接的用户和正在使用的 realm 必须具有必要的访问权限。在默认的 Keycloak 安装中，admin-cli 和 admin 用户都可以工作，同样，根据您的需求定制范围的单独 realm 定义以及具有预期角色的用户也可以工作。

• 模块选项的名称是 Keycloak API 及其文档中（https://keycloak.java.net.cn/docs-api/8.0/rest-api/index.html）中找到的 camelCase 名称的 snake_case 版本。提供了别名，以便可以使用 camelCased 版本。

• 此模块无法在导入后检测对实际加密密钥的更改。但是，如果与加密密钥一起更改其他属性，则密钥也会作为副作用发生更改，因为 JSON 负载需要包含私钥。这可以被认为是错误或功能，因为另一种方法是在密钥是否更改的情况下始终更新 realm 密钥。

• 如果未显式提供证书，则 Keycloak 将动态创建它。因此，无法将证书的当前状态与所需状态（可能为空）进行比较。

参数

参数	注释
auth_client_id 字符串	用于向 API 进行身份验证的 OpenID Connect client_id。 默认值： "admin-cli"
auth_client_secret 字符串	与 auth_client_id (如果需要)一起使用的客户端密钥。
auth_keycloak_url 别名：url 字符串 / 必需	Keycloak 实例的 URL。
auth_password 别名：password 字符串	用于 API 访问身份验证的密码。
auth_realm 字符串	用于 API 访问身份验证的 Keycloak realm 名称。
auth_username 别名：username 字符串	用于 API 访问身份验证的用户名。
config 字典	指定密钥及其属性的字典。
active 布尔值	密钥是处于活动状态还是非活动状态。不要与 state 参数管理的 Ansible 资源的状态混淆。 选项 false true ← (默认)
algorithm 字符串	密钥算法。 值 RS384、RS512、PS256、PS384、PS512、RSA1_5、RSA-OAEP、RSA-OAEP-256 已在 community.general 8.2.0 中添加。 选项 "RS256" ← (默认) "RS384" "RS512" "PS256" "PS384" "PS512" "RSA1_5" "RSA-OAEP" "RSA-OAEP-256"
certificate 字符串 / 必需	用私钥签名的证书，作为 ASCII 字符串。密钥的内容必须与 config.algorithm 和 provider_id 匹配。 如果您希望 Keycloak 使用您的私钥自动生成证书，则将其设置为空字符串。
enabled 布尔值	密钥是否启用或禁用。不要与由state参数管理的Ansible资源的状态混淆。 选项 false true ← (默认)
优先级 整数 / 必需	密钥的优先级。
私钥 字符串 / 必需	作为ASCII字符串的私钥。密钥的内容必须与config.algorithm和provider_id匹配。 请注意，模块无法检测指定的私钥是否与当前状态的私钥不同。如果预期更新私钥，请使用force=true强制模块更新私钥。
连接超时 整数 在community.general 4.5.0中添加	控制与Keycloak API的HTTP连接超时时间（以秒为单位）。 默认值： 10
强制 布尔值	强制执行私钥和证书的状态。这不是自动的，因为此模块无法确定私钥的当前状态，因此无法根据实际差异触发更新。也就是说，即使force为false，私钥更新也可能作为其他更改的副作用发生。 选项 false ← (默认) true
HTTP代理 字符串 在community.general 5.4.0中添加	配置HTTP User-Agent标头。 默认值： "Ansible"
名称 字符串 / 必需	要创建的Realm密钥的名称。
父ID 字符串 / 必需	Realm密钥的父ID。实际上是Realm的名称。
提供程序ID 字符串	密钥的“提供程序ID”的名称。 值rsa-enc已在community.general 8.2.0中添加。 选项 "rsa" ← (默认) "rsa-enc"
状态 字符串	Keycloak Realm密钥的状态。 在present上，将创建Realm密钥（如果已存在，则更新）。 在absent上，如果Realm密钥存在，则将其删除。 选项 "present" ← (默认) "absent"
令牌 字符串 在community.general 3.0.0中添加	Keycloak API 的身份验证令牌。
验证证书 布尔值	验证TLS证书（不要在生产环境中禁用此功能）。 选项 false true ← (默认)

属性

属性	支持	描述
check_mode	支持：完全支持	可以在check_mode下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：部分支持	在差异模式下，将返回有关已更改内容（或可能需要在check_mode中更改的内容）的详细信息。

备注

注意

• 无法从Keycloak获取私钥的当前值。因此，无法将它的期望状态与当前状态进行比较。

• 如果未显式提供证书，则 Keycloak 将动态创建它。因此，无法将证书的当前状态与所需状态（可能为空）进行比较。

• 由于私钥和证书选项，该模块**并非完全幂等**。如果您知道私钥可能已更改，可以使用force=true强制模块始终进行更新。

示例

- 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: https://127.0.0.1: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: https://127.0.0.1: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

返回值

常用的返回值已在此处记录，以下是此模块特有的字段

键	描述
最终状态 字典	模块执行后keycloak_realm_key的表示。 返回：成功时
config 字典	Realm密钥配置。 返回：当state=present时 示例： {"active": ["true"], "algorithm": ["RS256"], "enabled": ["true"], "priority": ["140"]}
ID 字符串	Realm密钥的ID。 返回：当state=present时 示例： "5b7ec13f-99da-46ad-8326-ab4c73cf4ce4"
名称 字符串	Realm密钥的名称。 返回：当state=present时 示例： "mykey"
parentId 字符串	此密钥所属的Realm的ID。 返回：当state=present时 示例： "myrealm"
providerId 字符串	密钥提供程序的ID。 返回：当state=present时 示例： "rsa"
providerType 字符串	提供程序的类型。 返回：当state=present时
消息 字符串	关于采取了什么行动的消息。 返回：始终

作者

• Samuli Seppänen (@mattock)

收藏链接

• 问题追踪器
• 代码库（源代码）
• 寻求帮助
• 提交错误报告
• 请求功能
• 沟通