community.general.keycloak_clienttemplate 模块 – 通过 Keycloak API 管理 Keycloak 客户端模板

注意

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

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

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

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

概要

• 此模块允许通过 Keycloak REST API 管理 Keycloak 客户端模板。它需要通过 OpenID Connect 访问 REST API；连接的用户和使用的客户端必须具有必要的访问权限。在默认的 Keycloak 安装中，admin-cli 和管理员用户都可以工作，单独的客户端定义（其范围根据您的需求进行调整）和具有预期角色的用户也可以工作。

• 模块选项的名称是 Keycloak API 及其文档（https://keycloak.com.cn/docs-api/8.0/rest-api/index.html）中找到的 camelCase 名称的 snake_case 版本。

• Keycloak API 并不总是强制仅使用合理的设置——例如，您可以在 OpenID Connect 客户端上设置 SAML 特定的设置，反之亦然。请小心。如果您没有指定设置，通常会选择合理的默认值。

参数

参数	注释
attributes 字典	此客户端模板的更多属性的字典。这可以包含各种配置设置，尽管在截至 3.4 版本的 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 访问身份验证的用户名。
connection_timeout 整数 community.general 4.5.0 中添加	控制对 Keycloak API 的 HTTP 连接超时时间（以秒为单位）。 默认值： 10
description 字符串	Keycloak 中客户端模板的描述。
full_scope_allowed 布尔值	是否为此客户端模板设置“允许完全范围”功能。这是 Keycloak REST API 中的“fullScopeAllowed”。 选项 false true
http_agent 字符串 community.general 5.4.0 中添加	配置 HTTP User-Agent 标头。 默认值： "Ansible"
id 字符串	要处理的客户端模板的 ID。这通常是 UUID。
name 字符串	客户端模板的名称。
protocol 字符串	客户端模板的类型。 docker-v2 值是在 community.general 8.6.0 中添加的。 选项 "openid-connect" "saml" "docker-v2"
protocol_mappers 列表 / 元素=字典	定义此客户端模板的协议映射器的字典列表。这是 Keycloak REST API 中的“protocolMappers”。
config 字典	字典，指定协议映射器的配置选项；其内容取决于protocol_mappers[].protocolMapper的值而有所不同，除了映射器的源代码及其父类(es)之外，没有其他文档说明。下面给出一个示例。最简单的方法是通过existing字段中的检查模式转储已存在的协议映射器配置来获取有效的配置值。
consentRequired 布尔值	指定用户是否需要为此映射器处于活动状态而向客户端提供同意。 选项 false true
consentText 字符串	呈现给用户以接受的同意的可读名称。
id 字符串	通常是 UUID，指定此协议映射器实例的内部 ID。
name 字符串	此协议映射器的名称。
protocol 字符串	这指定了此协议映射器处于活动状态的协议。 选项 "openid-connect" "saml" "docker-v2"
protocolMapper 字符串	此协议映射器类型的 Keycloak 内部名称。由于这可以通过 Keycloak 的用户通过 SPI 扩展，因此不可能提供详尽的列表，但默认情况下，截至 3.4 版本的 Keycloak 至少包含： docker-v2-allow-all-mapper oidc-address-mapper oidc-full-name-mapper oidc-group-membership-mapper oidc-hardcoded-claim-mapper oidc-hardcoded-role-mapper oidc-role-name-mapper oidc-script-based-protocol-mapper oidc-sha256-pairwise-sub-mapper oidc-usermodel-attribute-mapper oidc-usermodel-client-role-mapper oidc-usermodel-property-mapper oidc-usermodel-realm-role-mapper oidc-usersessionmodel-note-mapper saml-group-membership-mapper saml-hardcode-attribute-mapper saml-hardcode-role-mapper saml-role-list-mapper saml-role-name-mapper saml-user-attribute-mapper saml-user-property-mapper saml-user-session-note-mapper 您可以在管理员控制台中通过转到服务器信息 -> 提供程序并在“协议映射器”下查看来获取安装中可用映射器的完整列表。
realm 字符串	找到此客户端模板的 Realm。 默认值： "master"
state 字符串	客户端模板的状态。 在 present 状态下，将创建客户端模板（如果已存在则更新）。 在 absent 状态下，如果客户端模板存在，则将其删除。 选项 "present" ← (默认) "absent"
token 字符串 在 community.general 3.0.0 中添加	Keycloak API 的身份验证令牌。
validate_certs 布尔值	验证 TLS 证书（不要在生产环境中禁用此选项）。 选项 false true ← (默认)

属性

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

注释

注意

• Keycloak REST API 定义了其他字段（即 bearerOnly、consentRequired、standardFlowEnabled、implicitFlowEnabled、directAccessGrantsEnabled、serviceAccountsEnabled、publicClient 和 frontchannelLogout），虽然可以使用 keycloak_client，但它们对 Keycloak 客户端模板没有任何影响，如果使用更改客户端模板的 API 请求提供，则会被丢弃。因此，此模块中不提供这些字段。

示例

- name: Create or update Keycloak client template (minimal), authentication with credentials
  community.general.keycloak_client:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    realm: master
    name: this_is_a_test
  delegate_to: localhost

- name: Create or update Keycloak client template (minimal), authentication with token
  community.general.keycloak_clienttemplate:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    token: TOKEN
    realm: master
    name: this_is_a_test
  delegate_to: localhost

- name: Delete Keycloak client template
  community.general.keycloak_client:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    realm: master
    state: absent
    name: test01
  delegate_to: localhost

- name: Create or update Keycloak client template (with a protocol mapper)
  community.general.keycloak_client:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    realm: master
    name: this_is_a_test
    protocol_mappers:
      - config:
          access.token.claim: true
          claim.name: "family_name"
          id.token.claim: true
          jsonType.label: String
          user.attribute: lastName
          userinfo.token.claim: true
        consentRequired: true
        consentText: "${familyName}"
        name: family name
        protocol: openid-connect
        protocolMapper: oidc-usermodel-property-mapper
    full_scope_allowed: false
    id: bce6f5e9-d7d3-4955-817e-c5b7f8d65b3f
  delegate_to: localhost

返回值

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

键	描述
end_state 字典	模块执行后客户端模板的表示（示例已截断）。 返回：成功时 示例： {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", "protocol": "saml"}
existing 字典	现有客户端模板的表示（示例已截断）。 返回：始终返回 示例： {"description": "test01", "fullScopeAllowed": false, "id": "9c3712ab-decd-481e-954f-76da7b006e5f", "name": "test01", "protocol": "saml"}
msg 字符串	关于采取了什么操作的消息。 返回：始终返回 示例： "Client template testclient has been updated"
proposed 字典	建议的客户端模板的表示。 返回：始终返回 示例： {"name": "test01"}

作者

• Eike Frost (@eikef)

收藏链接

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