keycloak_group: fix subgroup lookup on Keycloak older than 25

The parents branch of get_group_by_name() queried
GET /admin/realms/{realm}/groups/{id}/children?search=&exact=true
unconditionally. That endpoint only accepts GET from Keycloak 23 on, so
older servers (RH-SSO 7.x included) failed with 405 Method Not Allowed,
and 23/24 ignore search/exact and return only the first 10 children, so
subgroups past the tenth were silently reported as absent.

The lookup now goes through get_subgroups(), which already detects the
server generation, and that helper takes an optional search argument so
the search optimization is kept where the server supports it.
This commit is contained in:
Yabk
2026-09-04 12:56:23 +02:00
parent 8d5526aeb6
commit 529b667321
3 changed files with 135 additions and 10 deletions
+56
View File
@@ -12,6 +12,7 @@
client: molecule-client
scope: molecule-scope
group: molecule-group
subgroup: molecule-subgroup
user: molecule-user
flow: molecule-flow
flow_v2: molecule-flow-v2
@@ -559,6 +560,61 @@
roles:
- name: "{{ client_role }}"
- name: keycloak_group — create subgroup below the parent group
middleware_automation.keycloak.keycloak_group:
realm: "{{ target_realm }}"
name: "{{ subgroup }}"
parents:
- name: "{{ group }}"
state: present
register: subgroup_result
- name: Assert subgroup was created below the parent group
ansible.builtin.assert:
that:
- subgroup_result is changed
- subgroup_result.end_state.path == '/' ~ group ~ '/' ~ subgroup
- name: keycloak_group — create enough siblings to exceed the children page size
middleware_automation.keycloak.keycloak_group:
realm: "{{ target_realm }}"
name: "{{ subgroup }}-{{ item }}"
parents:
- name: "{{ group }}"
state: present
loop: "{{ range(1, 13) | list }}"
- name: keycloak_group — look up a subgroup sorting past the children page size
middleware_automation.keycloak.keycloak_group:
realm: "{{ target_realm }}"
name: "{{ subgroup }}-9"
parents:
- name: "{{ group }}"
state: present
register: subgroup_paging_result
- name: Assert subgroup lookup is not limited to the first page of children
ansible.builtin.assert:
that:
- subgroup_paging_result is not changed
- subgroup_paging_result.end_state.path == '/' ~ group ~ '/' ~ subgroup ~ '-9'
- name: keycloak_realm_rolemapping — assign realm role to subgroup via parents
middleware_automation.keycloak.keycloak_realm_rolemapping:
realm: "{{ target_realm }}"
group_name: "{{ subgroup }}"
parents:
- name: "{{ group }}"
state: present
roles:
- name: "{{ role }}"
register: subgroup_rolemapping_result
- name: Assert realm role was mapped to the subgroup
ansible.builtin.assert:
that:
- subgroup_rolemapping_result is changed
- name: keycloak_client_rolescope — restrict realm role on client
middleware_automation.keycloak.keycloak_client_rolescope:
realm: "{{ target_realm }}"
+52
View File
@@ -6,6 +6,8 @@
keycloak_admin_user: "admin"
keycloak_uri: "http://localhost:8080"
keycloak_context: "/auth"
parent_group: molecule-parent-group
child_group: molecule-child-group
tasks:
- name: Populate service facts
ansible.builtin.service_facts:
@@ -24,3 +26,53 @@
until: keycloak_auth_response.status == 200
retries: 2
delay: 2
# This Keycloak is older than 23, so its group children endpoint accepts no
# GET request and the subgroup lookup has to fall back to the subgroups
# inlined in the parent group representation.
- name: Verify subgroup handling on a pre-23 Keycloak
module_defaults:
group/middleware_automation.keycloak.keycloak:
auth_keycloak_url: "{{ keycloak_uri }}{{ keycloak_context }}"
auth_realm: master
auth_username: "{{ keycloak_admin_user }}"
auth_password: "{{ keycloak_admin_password }}"
validate_certs: false
realm: master
block:
- name: keycloak_group — create parent group
middleware_automation.keycloak.keycloak_group:
name: "{{ parent_group }}"
state: present
- name: keycloak_group — create subgroup below the parent group
middleware_automation.keycloak.keycloak_group:
name: "{{ child_group }}"
parents:
- name: "{{ parent_group }}"
state: present
register: subgroup_result
- name: Assert subgroup was created below the parent group
ansible.builtin.assert:
that:
- subgroup_result is changed
- subgroup_result.end_state.path == '/' ~ parent_group ~ '/' ~ child_group
- name: keycloak_group — look the subgroup up through parents again
middleware_automation.keycloak.keycloak_group:
name: "{{ child_group }}"
parents:
- name: "{{ parent_group }}"
state: present
register: subgroup_lookup_result
- name: Assert the existing subgroup was found instead of re-created
ansible.builtin.assert:
that:
- subgroup_lookup_result is not changed
always:
- name: keycloak_group — remove parent group and its subtree
middleware_automation.keycloak.keycloak_group:
name: "{{ parent_group }}"
state: absent
@@ -1731,7 +1731,15 @@ class KeycloakAPI:
except Exception as e:
self.module.fail_json(msg=f"Could not fetch group {gid} in realm {realm}: {e}")
def get_subgroups(self, parent, realm: str = "master"):
def get_subgroups(self, parent, realm: str = "master", search=None):
"""Fetch the direct subgroups of a group.
:param parent: GroupRepresentation of the parent group
:param realm: Realm in which the group resides; default "master"
:param search: Optional group name, letting the server narrow the result
down. This is a hint only: servers which do not support searching
return all subgroups, so callers must still match names themselves.
"""
if "subGroupCount" in parent:
# Since version 23, when GETting a group Keycloak does not
# return subGroups but only a subGroupCount.
@@ -1740,9 +1748,17 @@ class KeycloakAPI:
group_children = []
else:
group_children_url = f"{URL_GROUP_CHILDREN.format(url=self.baseurl, realm=realm, groupid=parent['id'])}?max={parent['subGroupCount']}"
if search is not None:
# search/exact are only honoured from version 25 on, 23 and 24
# silently ignore them, which is why max is always sent as the
# full child count.
group_children_url += f"&search={quote(search, safe='')}&exact=true"
group_children = self._request_and_deserialize(group_children_url, method="GET")
subgroups = group_children
else:
# Before version 23 the children endpoint has no GET method at all
# (it answers 405 Method Not Allowed), the subgroups are inlined in
# the parent representation instead.
subgroups = parent["subGroups"]
return subgroups
@@ -1750,7 +1766,8 @@ class KeycloakAPI:
"""Fetch a keycloak group within a realm based on its name.
Uses the Keycloak search API with exact matching for efficient lookup
instead of fetching all groups.
instead of fetching all groups. Servers which do not support searching
are handled transparently, see the comments below.
If the group does not exist, None is returned.
:param name: Name of the group to fetch.
@@ -1764,18 +1781,18 @@ class KeycloakAPI:
if not parent:
return None
# For subgroups: use children endpoint with search parameter
search_url = "{url}?search={name}&exact=true".format(
url=URL_GROUP_CHILDREN.format(url=self.baseurl, realm=realm, groupid=parent["id"]),
name=quote(name, safe=""),
)
# For subgroups: search the parent's children where the server
# supports it. get_subgroups knows which servers those are, the
# exact name check below covers the ones which do not.
groups = self.get_subgroups(parent, realm, search=name)
else:
# For top-level groups: use groups endpoint with search parameter
# For top-level groups: use groups endpoint with search parameter.
# exact was only added in version 20; older servers ignore it and return
# substring matches, which the exact name check below sorts out.
search_url = "{url}?search={name}&exact=true".format(
url=URL_GROUPS.format(url=self.baseurl, realm=realm), name=quote(name, safe="")
)
groups = self._request_and_deserialize(search_url, method="GET")
groups = self._request_and_deserialize(search_url, method="GET")
# exact=true should return only exact matches, but verify the name
for group in groups: