Directory groups

The Directory groups screen lets you map the enterprise directory groups sent by Keycloak to a project, a role and an optional quota profile, and manage those quota profiles. Portal path: /admin/group-mappings. It is used by the tenant administrators (tenant_admin); security officers and auditors read it.

What the screen shows

At the top, the rule applied by the platform: "Applied at each sign-in from the groups claim: the membership and the quota are granted while the user is in the group and revoked when the group leaves the token. Memberships granted by hand are never removed. Keys and quotas live in the platform, not in LiteLLM."

Group mappings table, with Refresh and New mapping:

Column	Content
Group	Name of the directory group, as it appears in the groups or entra_groups claim of the token.
Project	Slug of the project the members join.
Role	Role granted: developer, viewer, auditor, finops, security_officer, agent or tenant_admin.
Quota profile	Name of the quota profile applied to each member, empty when none.
Active grants	Number of users who currently hold this mapping.
Updated	Date of the last change.

A click on a line opens a side panel with the mapping read from the API. Empty state: No group mapping.

Quota profiles table, with Refresh and New quota profile:

Column	Content
Name	Name of the profile.
Period	month, day, hour, run or request.
Enforcement	hard (blocks) or soft (warns).
Cost limit	Spend limit for the period.
Token limit	Token limit for the period.
Currency	Three-letter currency code of the cost limit.

Empty state: No quota profile, "Create a profile to give the members of a group a quota."

Actions

Button or action	What it does	API call	Roles
Opening the screen, Refresh (mappings)	Reads the mappings.	GET /v1/identity/group-mappings	tenant_admin, security_officer, auditor
New mapping then Create	Form Group (required, for example ai-risk-analysts), Project (required, project slug, for example risk), Role (required), Quota profile (profile name).	POST /v1/identity/group-mappings	tenant_admin
Click on a mapping	Opens the detail panel.	GET /v1/identity/group-mappings/{id}	tenant_admin, security_officer, auditor
Edit (mapping)	Dialog Group, Project, Role, Quota profile, Remove the quota profile, then Edit. The grants of the old definition are revoked; the next sign-in applies the new one.	PATCH /v1/identity/group-mappings/{id}	tenant_admin
Delete (mapping)	Destructive confirmation, then deletion; the memberships and quotas granted by the mapping are revoked.	DELETE /v1/identity/group-mappings/{id} (impact: GET /v1/lineage/graph)	tenant_admin
Refresh (profiles)	Reads the quota profiles.	GET /v1/identity/quota-profiles	tenant_admin, security_officer, auditor
New quota profile then Create	Form Name (required), Period (required), Enforcement, Cost limit, Token limit, Currency (for example EUR). A cost limit or a token limit is required.	POST /v1/identity/quota-profiles	tenant_admin
Edit (profile)	Dialog Period, Enforcement, Cost limit, Token limit. The user quotas already created from the profile are updated too.	PATCH /v1/identity/quota-profiles/{id}	tenant_admin
Delete (profile)	Destructive confirmation, then deletion. Refused while a mapping uses the profile.	DELETE /v1/identity/quota-profiles/{id} (impact: GET /v1/lineage/graph)	tenant_admin

Roles

From services/control-plane/src/eai/domains/identity/group_mappings.py: reading requires tenant_admin, security_officer or auditor (READ_ROLES, platform_admin always passes); creating, editing and deleting require tenant_admin. A group never grants platform_admin. The portal shows the buttons to every user; the server decides.

note

Memberships added by hand in Members and roles are never removed by a mapping. A membership granted by a mapping and then edited by an administrator becomes a manual one.

Typical tasks

Give the members of a directory group access to a project

1. Create a quota profile (optional). Button New quota profile: Name analysts, Period month, Enforcement hard, Cost limit 200, Currency EUR, then Create. Expected result: a new profile line. If it fails: validation_error (HTTP 422) when neither a cost limit nor a token limit is given; conflict (HTTP 409) when the name exists.
2. Create the mapping. Button New mapping: Group as sent by Keycloak (ai-risk-analysts), Project slug (risk), Role developer, Quota profile analysts, then Create. Expected result: a line with Active grants at 0. If it fails: not_found for an unknown project slug or profile name; conflict when the same group, project and role are already mapped.
3. Check at the next sign-in. Ask a member of the group to sign in again. Expected result: Active grants goes up and the member appears in Members and roles. If it fails: the token carries no groups claim or the group name differs (a leading / is ignored); check the Keycloak mapper.

Change the role given by a group

1. Edit the mapping. Row menu > Edit, choose the new Role, then Edit. Expected result: Active grants drops to 0, then grows again as the members sign in. If it fails: conflict when another mapping already has the same group, project and role.

Troubleshooting

Symptom	Cause	Fix
forbidden (HTTP 403) on the lists	Your role is not tenant_admin, security_officer nor auditor.	Ask a tenant administrator.
validation_error (HTTP 422) on a mapping	No project given.	Fill Project with a project slug.
validation_error (HTTP 422) on a profile	Neither Cost limit nor Token limit is filled.	Fill at least one limit.
not_found (HTTP 404)	Unknown project slug, profile name or identifier.	Check the slug in Projects and environments and the profile name in the table.
conflict (HTTP 409) on Delete of a profile	A mapping still uses the profile.	Edit the mappings with Remove the quota profile, then delete it.
Active grants stays at 0	No member signed in since the change, or the token has no group claim.	Ask a member to sign in again; check the groups mapper of Keycloak.

Related pages

• Members and roles
• Projects and environments
• Quotas
• Security documentation