OIDC groups claim from org teams (+ Parseable template) #5

Merged

franz merged 10 commits from feat/oidc-groups-claim into master

2026-06-29 16:22:15 +00:00

franz commented

2026-06-29 15:10:35 +00:00

Owner

OIDC `groups` claim from org teams

Adds a standard, flat groups OIDC claim so relying parties that map group names to roles (Parseable, Grafana, Argo CD, Kubernetes) work against Forseti out of the box. This is phase 1 of "roles & groups": governance roles (owner/member) are untouched; teams become the group source, with clean seams left for a future role catalog.

What it does

New groups OAuth scope. When granted, the id_token (and userinfo) carry "groups": [...], a flat array of the user's team slugs in their active org.
Sourced from existing teams (org_teams); no new tables, no migration.
Present-but-empty ([]) when the scope is granted and the user has no teams, so apps can tell "no groups" from "claim not requested".
Capped at 200 slugs with a groups_truncated boolean (operator/audit signal).
Emitted into the id_token only, never the access token. Re-resolved on every consent path (including remembered/skip consent); not on the refresh-token grant (per OIDC Core 12.2, matching Entra/Okta/Keycloak). A group change propagates on the next authorization.
Team slugs are now immutable on rename (rename changes the display name only), with an application-level collision guard, so a downstream role mapping never breaks under a rename.
groups_count / groups_truncated recorded in the OAUTH_CONSENT_GRANTED audit event.

Also included

A Parseable client template in /admin/clients/new (openid profile email groups, redirect /api/v1/o/code), with setup guidance for the P_OIDC_* env vars and the team-slug-to-role mapping.
Corrected the misleading "populate groups provider-side" notes on the argocd/harbor/portainer/proxmox/jellyfin/open_webui/gitlab templates, which Forseti now satisfies directly.
Docs: scope reference, id_token groups/groups_truncated tables, a group-based-roles section (including the cross-org slug caveat), and org-internals.

Known sharp edge

A groups-only token carries no org discriminator, and slugs are unique per org, not globally. An app deriving roles from bare slugs for a multi-org user should also request org and key on (org, slug), or restrict the client to a single org. Documented in the integration guide.

Testing

Unit tests cover the slug projection, rename immutability/collision, the helper query, scope description, and claim emission (absent/empty/truncated). Integration tests for the full consent flow are added and compile; they self-skip without a live Hydra/Kratos stack, so run them against the stack before relying on the merge.

Follow-ups (out of scope)

Refresh-token hook, wiring membership removal to consent-session revocation, a custom role catalog (phase 2), and a Parseable logo asset (currently a letter tile).

## OIDC `groups` claim from org teams Adds a standard, flat `groups` OIDC claim so relying parties that map group names to roles (Parseable, Grafana, Argo CD, Kubernetes) work against Forseti out of the box. This is phase 1 of "roles & groups": governance roles (`owner`/`member`) are untouched; teams become the group source, with clean seams left for a future role catalog. ### What it does - New `groups` OAuth scope. When granted, the id_token (and userinfo) carry `"groups": [...]`, a flat array of the user's **team slugs** in their **active org**. - Sourced from existing teams (`org_teams`); no new tables, no migration. - Present-but-empty (`[]`) when the scope is granted and the user has no teams, so apps can tell "no groups" from "claim not requested". - Capped at 200 slugs with a `groups_truncated` boolean (operator/audit signal). - Emitted into the id_token only, never the access token. Re-resolved on every consent path (including remembered/skip consent); not on the refresh-token grant (per OIDC Core 12.2, matching Entra/Okta/Keycloak). A group change propagates on the next authorization. - Team **slugs are now immutable on rename** (rename changes the display name only), with an application-level collision guard, so a downstream role mapping never breaks under a rename. - `groups_count` / `groups_truncated` recorded in the `OAUTH_CONSENT_GRANTED` audit event. ### Also included - A **Parseable** client template in `/admin/clients/new` (`openid profile email groups`, redirect `/api/v1/o/code`), with setup guidance for the `P_OIDC_*` env vars and the team-slug-to-role mapping. - Corrected the misleading "populate groups provider-side" notes on the argocd/harbor/portainer/proxmox/jellyfin/open_webui/gitlab templates, which Forseti now satisfies directly. - Docs: scope reference, id_token `groups`/`groups_truncated` tables, a group-based-roles section (including the cross-org slug caveat), and org-internals. ### Known sharp edge A `groups`-only token carries no org discriminator, and slugs are unique per org, not globally. An app deriving roles from bare slugs for a multi-org user should also request `org` and key on `(org, slug)`, or restrict the client to a single org. Documented in the integration guide. ### Testing Unit tests cover the slug projection, rename immutability/collision, the helper query, scope description, and claim emission (absent/empty/truncated). Integration tests for the full consent flow are added and compile; they self-skip without a live Hydra/Kratos stack, so run them against the stack before relying on the merge. ### Follow-ups (out of scope) Refresh-token hook, wiring membership removal to consent-session revocation, a custom role catalog (phase 2), and a Parseable logo asset (currently a letter tile).

franz added 9 commits

2026-06-29 15:10:35 +00:00

feat: make team slug immutable on rename, guard slug collisions f2a8d30b7b

feat: add group_slugs_for_identity helper for the groups claim 6fd512fcf9

feat: emit OIDC groups claim from active-org teams at consent 1bc817ca80

feat: describe the groups scope on the consent screen 234fdf991f

feat: record groups_count and groups_truncated in consent audit 2a0865f169

docs: correct app-template groups notes now that Forseti issues the claim 3ca429db84

test: integration coverage for the OIDC groups claim 5ed460da84

feat: add Parseable client template and document the groups scope 0ce0748760

docs: clarify groups claim cross-org slug caveat and freshness 8083595b8f

franz added 1 commit