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.java.net.cn/docs-api/8.0/rest-api/index.html）中找到的 camelCase 版本的 snake_cased 版本。

• 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 的值而异，除了映射器的源及其父类之外，没有其他文档。下面给出一个示例。最简单的方法是通过 existing 字段中的检查模式转储已经存在的协议映射器配置来获取有效的配置值。
consentRequired 布尔值	指定用户是否需要同意客户端才能使此映射器处于活动状态。 选择 false true
consentText 字符串	向用户显示的接受同意的人类可读名称。
id 字符串	通常是指定此协议映射器实例内部 ID 的 UUID。
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 字符串	此客户端模板所在的域。 默认值: "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	支持: 完整	当处于 diff 模式时，将返回有关已更改的内容（或可能需要在 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 字符串	有关采取的操作的消息。 返回: 总是 示例: "客户端模板 testclient 已更新"
proposed 字典	提议的客户端模板的表示形式。 返回: 总是 示例: {"name": "test01"}

作者

• Eike Frost (@eikef)

集合链接

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