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 和 admin 用户都可以工作，单独的客户端定义（其范围根据您的需求量身定制）和具有预期角色的用户也可以工作。

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

  • 属性在 Keycloak API 中是多值属性。所有属性都是单个值的列表，并且此模块将以这种方式返回它们。调用模块时，您可以为属性传递单个值，这将转换为适合 API 的列表。

参数

参数

注释

attributes

字典

设置为角色自定义属性的键值对字典。

值可以是单个值（例如字符串）或字符串列表。

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 访问身份验证的用户名。

client_id

字符串

如果角色是客户端角色，则为其所在的客户端 ID。

如果缺少此参数，则角色被视为 realm 角色。

composite

布尔值

community.general 7.1.0 中新增

如果为 true，则角色是其他 realm 和/或客户端角色的组合。

选项

  • false ← (默认)

  • true

composites

列表 / 元素=字典

community.general 7.1.0 中新增

要包含到组合 realm 角色中的角色列表。

如果组合角色是客户端角色，则必须指定 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 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 下更改的内容）的详细信息。

示例

- 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": "My updated client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"}

existing

字典

现有角色的表示。

返回值：始终返回

示例： {"attributes": {}, "clientRole": true, "composite": false, "containerId": "9f03eb61-a826-4771-a9fd-930e06d2d36a", "description": "My client test role", "id": "561703dd-0f38-45ff-9a5a-0c978f794547", "name": "myrole"}

msg

字符串

关于采取了什么操作的消息。

返回值：始终返回

示例： "Role myrole has been updated"

proposed

字典

建议的角色表示。

返回值：始终返回

示例： {"description": "My updated test description"}

作者

  • Laurent Paumier (@laurpaum)