community.general.keycloak_group 模块 – 通过 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_group。

概要

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

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

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

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

参数

参数	注释
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 访问身份验证的用户名。
connection_timeout 整数 在 community.general 4.5.0 中添加	控制对 Keycloak API 的 HTTP 连接超时时间（以秒为单位）。 默认值： 10
http_agent 字符串 在 community.general 5.4.0 中添加	配置 HTTP User-Agent 标头。 默认值： "Ansible"
id 字符串	此组的唯一标识符。 此参数对于更新或删除组不是必需的，但提供它将减少所需的 API 调用次数。
name 字符串	组的名称。 此参数仅在创建或更新组时才需要。
parents 列表 / 元素=字典 在 community.general 6.4.0 中添加	组的父组列表，用于处理自上而下的排序。 将其设置为将组创建为另一个组或组（父组）的子组，或者按名称访问现有子组时。 通过其 ID 访问现有子组时，无需设置此参数，因为在这种情况下，可以直接查询组，而无需知道其父组。
id 字符串	按 ID 标识父组。 比使用 parents[].name 需要更少的 API 调用。 当第一个父组以 ID 给出时，可以在任何点启动一个深度父链。 请注意，原则上可以同时指定 ID 和名称，但当前实现始终只使用其中一个，优先使用 ID。
name 字符串	按名称标识父组。 比使用 parents[].id 需要更多内部 API 调用来将名称映射到底层的 ID。 当只提供名称的父链时，必须完整到顶层。 请注意，原则上可以同时指定 ID 和名称，但当前实现始终只使用其中一个，优先使用 ID。
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 模式下更改的内容）的详细信息。

备注

注意

• 目前，Keycloak API 返回的 end_state.realmRoles、end_state.clientRoles 和 end_state.access 属性对于组是只读的。此限制将在该模块的后续版本中移除。

示例

- name: Create a Keycloak group, authentication with credentials
  community.general.keycloak_group:
    name: my-new-kc-group
    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
  register: result_new_kcgrp
  delegate_to: localhost

- name: Create a Keycloak group, authentication with token
  community.general.keycloak_group:
    name: my-new-kc-group
    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 group
  community.general.keycloak_group:
    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 group based on name
  community.general.keycloak_group:
    name: my-group-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 group
  community.general.keycloak_group:
    id: '9d59aa76-2755-48c6-b1af-beb70a82c3cd'
    name: an-updated-kc-group-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 group with some custom attributes
  community.general.keycloak_group:
    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_group
    attributes:
        attrib1: value1
        attrib2: value2
        attrib3:
            - with
            - numerous
            - individual
            - list
            - items
  delegate_to: localhost

- name: Create a Keycloak subgroup of a base group (using parent name)
  community.general.keycloak_group:
    name: my-new-kc-group-sub
    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
    parents:
      - name: my-new-kc-group
  register: result_new_kcgrp_sub
  delegate_to: localhost

- name: Create a Keycloak subgroup of a base group (using parent id)
  community.general.keycloak_group:
    name: my-new-kc-group-sub2
    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
    parents:
      - id: "{{ result_new_kcgrp.end_state.id }}"
  delegate_to: localhost

- name: Create a Keycloak subgroup of a subgroup (using parent names)
  community.general.keycloak_group:
    name: my-new-kc-group-sub-sub
    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
    parents:
      - name: my-new-kc-group
      - name: my-new-kc-group-sub
  delegate_to: localhost

- name: Create a Keycloak subgroup of a subgroup (using direct parent id)
  community.general.keycloak_group:
    name: my-new-kc-group-sub-sub
    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
    parents:
      - id: "{{ result_new_kcgrp_sub.end_state.id }}"
  delegate_to: localhost

返回值

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

键	描述
end_state 复杂类型	模块执行后组的表示（示例已截断）。 返回：成功时
access 字典	一个字典，描述您基于所使用的凭据对该组的访问权限。 返回：始终返回 示例： {"manage": true, "manageMembership": true, "view": true}
attributes 字典	应用于此组的属性。 返回：始终返回 示例： {"attr1": ["val1", "val2", "val3"]}
clientRoles 列表 / 元素=字符串	授予此组的客户端级别角色列表。 返回：始终返回 示例： []
id 字符串	标识组的 GUID。 返回：始终返回 示例： "23f38145-3195-462c-97e7-97041ccea73e"
name 字符串	组的名称。 返回：始终返回 示例： "grp-test-123"
path 字符串	指向该组的 URI 路径。 返回：始终返回 示例： "/grp-test-123"
realmRoles 列表 / 元素=字符串	授予此组的 realm 级别角色数组。 返回：始终返回 示例： []
subGroups 列表 / 元素=字符串	此组的子组列表。这些组将具有此处记录的相同参数。 返回：始终返回
msg 字符串	关于采取了什么操作的消息。 返回：始终返回

作者

• Adam Goossens (@adamgoossens)

收藏链接

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