Keycloak 26.6 - How to configure realm roles using new feature Organization Groups? #48061

ricardomarks · 2026-04-14T19:34:07Z

ricardomarks
Apr 14, 2026

Bug / Missing Feature: No API endpoint to assign role mappings to Organization Groups (introduced in 26.6.0)

Keycloak version: 26.6.0
Component: Organizations / Groups / Admin REST API / Admin UI

Description

Keycloak 26.6.0 introduced support for organization-specific group hierarchies, allowing each organization to manage its own isolated groups. However, there is no clear or documented way to assign role mappings to these organization groups — neither via the Admin REST API nor via the Admin UI.

Steps to Reproduce

Via Admin REST API

Enable the Organizations feature in a realm.
Create an Organization.
Create a group within that Organization (via the Organization API).
Attempt to assign realm roles to that group using the standard Groups role-mappings endpoint:

Actual Behavior

REST API: The following error is returned when calling the standard Groups role-mappings endpoint:
POST /admin/realms/{realm}/groups/{groupId}/role-mappings/realm

HTTP 400 Bad Request

{
  "errorMessage": "Cannot manage organization related group via non Organization API."
}

Questions

Is role mapping on organization groups an intentional omission or a missing feature?
Was the decision to block the standard /groups/{id}/role-mappings endpoint for org groups deliberate, or is this something that was simply not yet implemented as part of the 26.6.0 scope?
Should role mappings on org groups be managed through the Organization API or the Groups API?
Given that org groups are explicitly isolated from realm groups and must be managed through the Organization API, should role mappings follow the same restriction? Or would it make sense to extend the existing Groups role-mappings endpoint to support org groups as a special case?
Should role mappings on org groups be scoped to organization roles only, or should realm roles also be assignable?
For example, should it be possible to assign a realm-level role to an org group, or should only organization-specific roles be allowed? This has direct implications on the API path and the authorization model.
What is the recommended workaround in the meantime?
Is there a supported way to achieve role-based access control for org group members today, while this feature is not yet available? For example, should roles be assigned directly to users instead of groups?
Will the Admin UI be updated to reflect the supported behavior?
Once the intended approach is defined, is there a plan to expose role mapping for org groups in the Admin Console, similar to the Role Mapping tab available for regular realm groups?

zuhairhalawa · 2026-10-23T21:27:39Z

zuhairhalawa
Oct 23, 2026

Short version: on 26.6.x this isn't possible. From 26.7.0 it is, through the Organization API.

On 26.6.x it's a missing feature, not a decision about roles:

The 26.6 docs list "Role assignment: Not supported (coming in future releases)" for organization groups.
GroupsResource#getGroupById rejects organization groups with the 400 you saw. That isolation is intentional and still present in 26.8, so /groups/{id}/role-mappings will never work for them.
In 26.6.x OrganizationGroupResource has no role-mappings sub-resource, and the admin console hides the Role mapping tab for org groups.

26.7.0 added it (issue #47327, PR #48670, release notes: "Automatic role inheritance through organization groups"). Role mappings now live under the Organization API and accept realm and client roles:

GET|POST|DELETE /admin/realms/{realm}/organizations/{org-id}/groups/{group-id}/role-mappings/realm
GET|POST|DELETE /admin/realms/{realm}/organizations/{org-id}/groups/{group-id}/role-mappings/clients/{client-uuid}

The body is the usual list of role representations ([{"id": "...", "name": "..."}]), and the console shows a Role mapping tab for org groups. According to the docs you need manage-organizations (or an FGAP permission on the organization) plus map-role on each role. Roles of org groups end up in realm_access / resource_access; enabling "Add group role mappings" on the Organization Group Membership mapper also nests them in the organization claim.

Until you can upgrade: assign the roles directly to the users, or use a realm group or composite role.

0 replies

Navigation Menu

Repository navigation

Keycloak 26.6 - How to configure realm roles using new feature Organization Groups? #48061

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Select a reply

Uh oh!

Keycloak 26.6 - How to configure realm roles using new feature Organization Groups? #48061

Uh oh!

ricardomarks Apr 14, 2026

Bug / Missing Feature: No API endpoint to assign role mappings to Organization Groups (introduced in 26.6.0)

Description

Steps to Reproduce

Actual Behavior

Questions

Replies: 1 comment

Uh oh!

Uh oh!

zuhairhalawa Oct 23, 2026

ricardomarks
Apr 14, 2026

zuhairhalawa
Oct 23, 2026