community.general.keycloak_realm_rolemapping 模块 – 使用 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_realm_rolemapping。

community.general 8.2.0 中的新增功能

概要

  • 此模块允许您使用 Keycloak REST API 向组添加、删除或修改 Keycloak 领域角色映射。它需要通过 OpenID Connect 访问 REST API；连接的用户和使用的客户端必须具有必要的访问权限。在默认的 Keycloak 安装中，admin-cli 和管理员用户都可以工作，单独的客户端定义（范围根据您的需求定制）和拥有预期角色的用户也可以工作。

  • 模块选项的名称是 Keycloak API 及其文档中找到的 camelCase 名称的 snake_cased 版本，请访问 https://keycloak.java.net.cn/docs-api/18.0/rest-api/index.html。

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

  • 更新 group_rolemapping 时，如果可能，请向模块提供角色 ID。这将删除将名称转换为角色 ID 的 API 查找。

参数

参数

注释

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 领域名称。

auth_username

别名：username

字符串

用于 API 访问身份验证的用户名。

connection_timeout

整数

community.general 4.5.0 中添加

控制对 Keycloak API 的 HTTP 连接超时时间（以秒为单位）。

默认值： 10

gid

字符串

要映射的组的 ID。

此参数对于更新或删除角色映射不是必需的，但提供它会减少所需的 API 调用次数。

group_name

字符串

要映射的组的名称。

此参数是必需的（可以使用 gid 替换以减少 API 调用次数）。

http_agent

字符串

community.general 5.4.0 中添加

配置 HTTP User-Agent 标头。

默认值： "Ansible"

parents

列表 / 元素=字典

要处理的组的父组列表，按从上到下的顺序排序。

如果您的组是子组并且您没有在 gid 中提供 GID，则设置此项。

id

字符串

按 ID 标识父项。

比使用 parents[].name 需要更少的 API 调用次数。

当第一个父项作为 ID 给出时，可以在任何点开始深度父链。

请注意，原则上可以同时指定 ID 和名称，但当前实现始终只使用其中一个，优先使用 ID。

名称

字符串

按名称识别父级。

比使用parents[].id 需要更多的内部 API 调用来将名称映射到底层的 ID。

当只使用名称给出父级链时，它必须完整到顶部。

请注意，原则上可以同时指定 ID 和名称，但当前实现始终只使用其中一个，优先使用 ID。

区域

字符串

此角色表示所在的 Keycloak 区域。

默认值："master"

角色

列表 / 元素=字典

要映射到组的角色。

id

字符串

此角色表示的唯一标识符。

此参数对于更新或删除角色表示不是必需的，但提供它将减少所需的 API 调用次数。

名称

字符串

角色表示的名称。

此参数仅在创建或更新角色表示时需要。

状态

字符串

区域角色映射的状态。

在present 上，如果区域角色映射尚不存在，则会创建它，或者使用您提供的参数进行更新。

在absent 上，如果区域角色映射存在，则会将其删除。

选项

  • "present" ← (默认)

  • "absent"

令牌

字符串

在 community.general 3.0.0 中添加

Keycloak API 的身份验证令牌。

验证证书

布尔值

验证 TLS 证书（不要在生产环境中禁用此功能）。

选项

  • false

  • true ← (默认)

属性

属性

支持

描述

check_mode

支持：完全支持

可以在check_mode 中运行，并在不修改目标的情况下返回更改状态预测。

diff_mode

支持：完全支持

在差异模式下，将返回有关已更改内容（或可能需要在check_mode 中更改）的详细信息。

示例

- name: Map a client role to a group, authentication with credentials
  community.general.keycloak_realm_rolemapping:
    realm: MyCustomRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    state: present
    group_name: group1
    roles:
      - name: role_name1
        id: role_id1
      - name: role_name2
        id: role_id2
  delegate_to: localhost

- name: Map a client role to a group, authentication with token
  community.general.keycloak_realm_rolemapping:
    realm: MyCustomRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    token: TOKEN
    state: present
    group_name: group1
    roles:
      - name: role_name1
        id: role_id1
      - name: role_name2
        id: role_id2
  delegate_to: localhost

- name: Map a client role to a subgroup, authentication with token
  community.general.keycloak_realm_rolemapping:
    realm: MyCustomRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    token: TOKEN
    state: present
    group_name: subgroup1
    parents:
      - name: parent-group
    roles:
      - name: role_name1
        id: role_id1
      - name: role_name2
        id: role_id2
  delegate_to: localhost

- name: Unmap realm role from a group
  community.general.keycloak_realm_rolemapping:
    realm: MyCustomRealm
    auth_client_id: admin-cli
    auth_keycloak_url: https://auth.example.com/auth
    auth_realm: master
    auth_username: USERNAME
    auth_password: PASSWORD
    state: absent
    group_name: group1
    roles:
      - name: role_name1
        id: role_id1
      - name: role_name2
        id: role_id2
  delegate_to: localhost

返回值

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

键

描述

end_state

字典

模块执行后客户端角色映射的表示。

示例已截断。

返回：成功时

示例：{"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

existing

字典

现有客户端角色映射的表示。

示例已截断。

返回：始终

示例：{"adminUrl": "http://www.example.com/admin_url", "attributes": {"request.object.signature.alg": "RS256"}}

msg

字符串

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

返回：始终

示例："Role role1 assigned to group group1."

proposed

字典

建议的客户端角色映射的表示。

返回：始终

示例：{"clientId": "test"}

作者

  • Gaëtan Daubresse (@Gaetan2907)

  • Marius Huysamen (@mhuysamen)

  • Alexander Groß (@agross)