community.general.keycloak_role 模块 – 允许通过 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_role。

community.general 3.4.0 中的新增功能

概要 

此模块允许您通过 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。
属性在 Keycloak API 中是多值的。所有属性都是单个值的列表，并且将通过此模块以这种方式返回。您可以在调用模块时为属性传递单个值，这将转换为适合 API 的列表。

参数 

参数	注释
attributes 字典	要设置为角色自定义属性的键/值对字典。值可以是单个值（例如，字符串）或字符串列表。
auth_client_id 字符串	OpenID Connect `client_id` 用于向 API 进行身份验证。默认值： `"admin-cli"`
auth_client_secret 字符串	与 `auth_client_id` 结合使用的客户端密钥（如果需要）。
auth_keycloak_url 别名：url 字符串 / 必需	Keycloak 实例的 URL。
auth_password 别名：password 字符串	用于 API 访问的身份验证密码。
auth_realm 字符串	用于 API 访问的身份验证 Keycloak 领域名称。
auth_username 别名：username 字符串	用于 API 访问的身份验证用户名。
client_id 字符串	如果角色是客户端角色，则它所在的客户端 ID。如果此参数不存在，则该角色被视为领域角色。
composite 布尔值在 community.general 7.1.0 中添加	如果 `true`，则该角色是其他领域和/或客户端角色的组合。选择 `false` ← （默认值） `true`
composites 列表 / 元素=字典在 community.general 7.1.0 中添加	要包含在复合领域角色中的角色列表。如果复合角色是客户端角色，则必须指定 `clientId`（不是客户端的 ID）。默认值： `[]`
client_id 别名：clientId 字符串	如果角色是客户端角色，则为客户端 ID。不要为 REALM 角色包含此选项。使用您可以在 Keycloak 控制台中看到的客户端 ID，而不是客户端的技术 ID。
name 字符串 / 必需	角色的名称。这可以是 REALM 角色或客户端角色的名称。
state 字符串	如果存在，则创建复合角色，如果不存在，则删除复合角色。选择 `"present"` ← （默认值） `"absent"`
connection_timeout 整数在 community.general 4.5.0 中添加	控制 Keycloak API 的 HTTP 连接超时时间（以秒为单位）。默认值： `10`
description 字符串	角色描述。
http_agent 字符串在 community.general 5.4.0 中添加	配置 HTTP User-Agent 标头。默认值： `"Ansible"`
name 字符串 / 必需	角色的名称。此参数是必需的。
realm 字符串	此角色所在的 Keycloak 领域。默认值： `"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` 模式下更改）的详细信息。

示例 

- name: Create a Keycloak realm role, authentication with credentials
  community.general.keycloak_role:
    name: my-new-kc-role
    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 realm role, authentication with token
  community.general.keycloak_role:
    name: my-new-kc-role
    realm: MyCustomRealm
    state: present
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    token: TOKEN
  delegate_to: localhost

- name: Create a Keycloak client role
  community.general.keycloak_role:
    name: my-new-kc-role
    realm: MyCustomRealm
    client_id: MyClient
    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: Delete a Keycloak role
  community.general.keycloak_role:
    name: my-role-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: Create a keycloak role with some custom attributes
  community.general.keycloak_role:
    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-role
    attributes:
        attrib1: value1
        attrib2: value2
        attrib3:
            - with
            - numerous
            - individual
            - list
            - items
  delegate_to: localhost

返回值 

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

键	描述
end_state 字典	模块执行后角色的表示形式（示例已截断）。返回: 成功时示例: `{"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a", "description": "我的更新的客户端测试角色", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"}`
existing 字典	现有角色的表示形式。返回: 始终示例: `{"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a", "description": "我的客户端测试角色", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"}`
msg 字符串	关于采取了什么操作的消息。返回: 始终示例: `"角色 myrole 已更新"`
proposed 字典	提议角色的表示形式。返回: 始终示例: `{"description": "我的更新的测试描述"}`

作者

Laurent Paumier (@laurpaum)