Keycloak API modules - subgroups issue | Keycloak > 23.0.7 incompatability

[UKFr-DIZ]

Summary

Description:

There is an issue with the Keycloak Ansible modules in the community.general collection that affects compatibility with Keycloak versions greater than 23.0.7. The problem stems from a change in the Keycloak API representation, specifically related to the handling of subgroups.

Background:

Keycloak 23.0.7 introduced a change in how the subGroups attribute is represented when fetching group data via the Keycloak API. According to the Keycloak Upgrade Documentation, the subGroups field is now always returned as an empty list, even if the subGroupCount indicates that subgroups exist. This behavior was introduced for backward compatibility, but it has led to issues where the actual subgroups are not fetched using the traditional GET /groups endpoint.

The new recommended approach to fetch subgroups is by using the GET /realms/{realm}/groups/{group_id}/children endpoint.

Affected Modules:

All Keycloak Ansible modules that interact with subgroups are affected. Specifically, this issue is similar to the one reported in issue #7650, but it should be mentioned that this change in keycloak API impacts a broader set of modules.

I am personally affected using the module community.general.keycloak_client_rolemapping

In the code the issue is due to :

community.general/plugins/module_utils/identity/keycloak/keycloak.py

Line 1572 in e3a3c6d

for sg in tmp['subGroups']:

receives always an empty list --> won't work.

Solution:

To maintain compatibility with newer Keycloak versions, the affected Ansible modules (specifically those in plugins/module_utils/identity/keycloak/keycloak.py) need to be updated to utilize the new API endpoint {keycloak server}/realms/{realm}/groups/{group_id}/children for fetching subgroups. This change will ensure that the modules can correctly handle and interact with subgroups in Keycloak environments running version 23.0.7 or later.

Impact:

Ansible keycloak modules are not (fully) compatible with Keycloak 23.0.7 or later.

BR

Issue Type

Bug Report

Component Name

plugins/module_utils/identity/keycloak/keycloak.py

Ansible Version

$ ansible --version
ansible [core 2.15.9]
  config file = /opt/ansible/worktree/ths/ansible.cfg
  configured module search path = ['/home/ansible-adm/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /opt/ansible/env/lib/python3.10/site-packages/ansible
  ansible collection location = /home/ansible-adm/.ansible/collections:/usr/share/ansible/collections
  executable location = /opt/ansible/env/bin/ansible
  python version = 3.10.12 (main, Jul 29 2024, 16:56:48) [GCC 11.4.0] (/opt/ansible/env/bin/python)
  jinja version = 3.1.2
  libyaml = True

Community.general Version

$ ansible-galaxy collection list community.general
Collection        Version
----------------- -------
community.general 9.3.0

Configuration

$ ansible-config dump --only-changed

OS / Environment

Ubuntu 22

Steps to Reproduce

Keycloak version

quay.io/keycloak/keycloak:25.0.2

Used module example:
keycloak_client_rolemapping

- name: do rolemaping
  community.general.keycloak_client_rolemapping:
    <<: *kc_auth_args
    state: present
    realm: realm
    group_name: subgroup1
    parents:
      - id: parent_group
    client_id: client1
    roles:
      - name: role1

• have keycloak in version 23.0.7> with a small group tree representation
  • parent_group
    • subgroup1
    • subgroup2

Sample API Response:

Here’s an example of the current response from the GET /groups API call with recent Keycloak version 25.0.2:

{
  "id": "7ab2bc07-9fce-4a04-955e-65cf1112a80a",
  "name": "parent_group",
  "path": "/parent_group",
  "subGroupCount": 2,
  "subGroups": [],
  "attributes": {},
  "realmRoles": [],
  "clientRoles": {
    "client1": ["role1"]
  },
  "access": {
    "view": true,
    "viewMembers": true,
    "manageMembers": true,
    "manage": true,
    "manageMembership": true
  }
}

Even though subGroupCount is 2, the subGroups array is empty. This leads to errors or incorrect behavior in Ansible modules that rely on this attribute.
To get represetation you should use: groups/7ab2bc07-9fce-4a04-955e-65cf1112a80a/children

Expected Results

playbook runs and does the mapping and succesfully fetches the subgroups based on the parentgroup parameters

Actual Results

FAILED! => changed=false 
  msg: 'Could not fetch group subgroup1:'

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[ansibullbot]

Files identified in the description:

• plugins/module_utils/identity/keycloak/keycloak.py

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[ansibullbot]

cc @eikef @mattock @ndclt @thomasbach-dev
click here for bot help