community.general.keycloak_clientscope 模块 – 允许通过 Keycloak API 管理 Keycloak client_scopes

注意

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

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

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

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

community.general 3.4.0 中的新增功能

概要

• 此模块允许您通过 Keycloak REST API 添加、删除或修改 Keycloak client_scopes。它需要通过 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 中是多值的。所有属性都是单个值的列表，并且将由此模块以这种方式返回。您可以在调用模块时传递属性的单个值，这将转换为适合 API 的列表。

• 在更新 client_scope 时，如果可能，请向模块提供 client_scope ID。这将消除对 API 的查找以将名称转换为 client_scope ID。

参数

参数	注释
attributes 字典	一个键/值对的字典，用于设置为 client_scope 的自定义属性。 值可以是单个值（例如字符串）或字符串列表。
auth_client_id 字符串	用于通过 OpenID Connect 验证 API 的 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 字符串	此 client_scope 的描述。 此参数不是更新或删除 client_scope 所必需的。
http_agent 字符串 在 community.general 5.4.0 中添加	配置 HTTP User-Agent 标头。 默认值： "Ansible"
id 字符串	此 client_scope 的唯一标识符。 此参数不是更新或删除 client_scope 所必需的，但提供它可以减少所需的 API 调用次数。
name 字符串	client_scope 的名称。 此参数仅在创建或更新 client_scope 时是必需的。
protocol 字符串	客户端类型。 docker-v2 值已在 community.general 8.6.0 中添加。 选项 "openid-connect" "saml" "wsfed" "docker-v2"
protocol_mappers 别名：protocolMappers 列表 / elements=dictionary	一个字典列表，用于定义此客户端的协议映射器。 这是 Keycloak REST API 中的 “protocolMappers”。
config 字典	一个字典，指定协议映射器的配置选项；内容因 protocol_mappers[].protocolMapper 的值而异，并且除了映射器的源及其父类之外没有其他文档。下面给出一个示例。通过在 existing 返回值中的检查模式下转储已存在的协议映射器配置，最容易获得有效的配置值。
id 字符串	通常是一个 UUID，指定此协议映射器实例的内部 ID。
name 字符串	此协议映射器的名称。
protocol 字符串	这指定此协议映射器用于哪个协议。 处于活动状态。 选项 "openid-connect" "saml" "wsfed" "docker-v2"
protocolMapper 字符串	此协议映射器的 Keycloak 内部类型名称。虽然无法提供详尽的列表，因为用户可以通过 Keycloak 的 SPI 扩展此列表，但默认情况下，Keycloak 3.4 及更高版本至少包含以下映射器： 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 字符串	此 client_scope 所在的 Keycloak realm。 默认值： "master"
state 字符串	client_scope 的状态。 设置为 present 时，如果 client_scope 尚不存在，则会创建它；如果存在，则会使用您提供的参数更新它。 设置为 absent 时，如果 client_scope 存在，则会将其删除。 选项 "present" ← (默认值) "absent"
token 字符串 在 community.general 3.0.0 中添加。	Keycloak API 的身份验证令牌。
validate_certs 布尔值	验证 TLS 证书（在生产环境中不要禁用此项）。 选项 false true ← (默认值)

属性

属性	支持	描述
check_mode	支持：完全	可以在 check_mode 中运行，并返回更改的状态预测，而无需修改目标。
diff_mode	支持：完全	当处于 diff 模式时，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息。

示例

- name: Create a Keycloak client_scopes, authentication with credentials
  community.general.keycloak_clientscope:
    name: my-new-kc-clientscope
    realm: MyCustomRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

- name: Create a Keycloak client_scopes, authentication with token
  community.general.keycloak_clientscope:
    name: my-new-kc-clientscope
    realm: MyCustomRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    token: TOKEN
  delegate_to: localhost

- name: Delete a keycloak client_scopes
  community.general.keycloak_clientscope:
    id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd'
    state: absent
    realm: MyCustomRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

- name: Delete a Keycloak client_scope based on name
  community.general.keycloak_clientscope:
    name: my-clientscope-for-deletion
    state: absent
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

- name: Update the name of a Keycloak client_scope
  community.general.keycloak_clientscope:
    id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd'
    name: an-updated-kc-clientscope-name
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
  delegate_to: localhost

- name: Create a Keycloak client_scope with some custom attributes
  community.general.keycloak_clientscope:
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    name: my-new_clientscope
    description: description-of-clientscope
    protocol: openid-connect
    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
        name: family name
        protocol: openid-connect
        protocolMapper: oidc-usermodel-property-mapper
      - config:
          attribute.name: Role
          attribute.nameformat: Basic
          single: false
        name: role list
        protocol: saml
        protocolMapper: saml-role-list-mapper
    attributes:
        attrib1: value1
        attrib2: value2
        attrib3:
            - with
            - numerous
            - individual
            - list
            - items
  delegate_to: localhost

返回值

常见的返回值记录在这里，以下是此模块独有的字段

键	描述
end_state 字典	模块执行后 client scope 的表示形式（示例被截断）。 返回： 成功时 示例： {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
existing 字典	现有 client scope 的表示形式（示例被截断）。 返回： 始终 示例： {"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}
msg 字符串	关于采取了什么操作的消息。 返回： 始终 示例： "Client_scope testclientscope has been updated"
proposed 字典	建议的 client scope 的表示形式。 返回： 始终 示例： {"clientId": "test"}

作者

• Gaëtan Daubresse (@Gaetan2907)

集合链接

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