Settings: SSO Group Mappings

Map OIDC group claims to PodWarden roles with the group mappings admin panel and claim-preview tool

Overview

URL: /settings (SSO tab)

The SSO Group Mappings panel lets you control which PodWarden roles are granted to users when they sign in via OIDC. Mappings work on group claim values — a string your identity provider includes in the JWT (e.g. groups: ["platform-admins", "viewers"]). When a user signs in, PodWarden evaluates all mappings and applies any that match, building an additive (include-only union) of roles.

This tab is only visible to admin users.

How matching works

PodWarden reads the claim path configured in Settings → System (e.g. groups, realm_access.roles).
Every mapping whose group_claim_value exactly matches one of the user's group claim values is applied.
All matched mappings are additive — if a user matches three mappings that grant Viewer, Editor, and Admin, they receive all three roles.
Matching is case-sensitive. "Platform-Admins" and "platform-admins" are different values.
Scope restricts where a role applies: a global mapping grants the role on every cluster; a cluster mapping grants it only on the named cluster.

Mapping fields

Field	Description
Provider name	Must match the `provider_name` configured in Settings → System. Pre-filled automatically.
Group claim value	The exact string from the OIDC groups claim. Case-sensitive.
Role	One of the five seeded roles: Owner, Admin, Editor, Viewer, Operator.
Scope kind	`global` — applies to all clusters. `cluster` — applies to one named cluster.
Cluster name	Required when scope kind is `cluster`. Select from your provisioned clusters.
Priority	An integer used for ordering and audit. Priority is NOT an override and does not suppress other matched mappings — all matches are still applied.

Creating a mapping

Click Add mapping… in the SSO tab toolbar.
Fill in all required fields (provider name is pre-filled from your OIDC configuration).
Click Save mapping.
Use the Claim Preview Tool (see below) to verify the mapping behaves as expected before users sign in.

Editing and deleting

Click the Edit button on any row to open the edit form. All fields are editable.
Click Delete and confirm to remove a mapping. Existing SSO-managed role bindings are not removed immediately — they are reaped on the affected users' next sign-in.

SSO-managed vs manual bindings

PodWarden distinguishes two kinds of role bindings:

Kind	`is_sso_managed`	Created by	Removed when
SSO-managed	`true`	Automatically on each OIDC sign-in (when a mapping matches)	The group is no longer in the user's claim, the mapping is deleted, or the user account is suspended
Manual	`false`	Admin grants via Settings → Users	Only when an admin explicitly removes it

Manual bindings are never touched by the OIDC reconciliation loop — they survive group changes and mapping updates. Use them for service accounts or admin users who should always have access regardless of their OIDC groups.

Claim Preview Tool

The Claim Preview Tool is a safety guard that lets you test your mappings against a real or sample JWT claim payload before deploying changes. It is strongly recommended before adding any new mapping or changing the groups_claim path.

How to use it

Paste a JWT claim payload (the JSON body of the JWT, not the full encoded token) into the Claim payload field. Example:

{
  "sub": "user-uuid",
  "email": "[email protected]",
  "groups": ["platform-admins", "cluster-viewers"]
}

Optionally enter a groups_claim override to test a different claim path than the one currently configured (useful when migrating from one IdP to another). Leave blank to use the path in Settings → System.
Click Run preview.

Reading the results

Section	Colour	What it means
Would reap	Amber	With this claim, existing SSO-managed bindings that are no longer matched would be removed on the user's next sign-in. Manual bindings (`is_sso_managed=false`) are never affected by the reap.
Case mismatch warnings	Amber	A mapping exists, but the case does not match (e.g. claim has `Platform-Admins`, mapping expects `platform-admins`). The mapping will NOT apply. Fix the mapping value or your IdP group name.
Dead scope mappings	Red	A mapping references a cluster that no longer exists. The mapping can never produce a binding. Delete or update it.
Matched mappings	Green	These mappings will apply — the user receives these roles.

Common pitfalls

Case sensitivity: matching is byte-exact. Use the claim preview to verify casing before saving mappings.
Dotted-path claims: if your groups are nested (e.g. realm_access.roles), configure the groups_claim path in Settings → System. The claim preview uses the same path, so pasting a full JWT payload will test the correct field.
Dead-scope mappings: if you delete a cluster, mappings referencing it become dead-scope — they never match but still appear in the list. Use the claim preview to surface them, then delete them.

Related docs

Settings — System — Configure OIDC provider, groups_claim path, and no_match_posture
Settings — Users — Manage local users and manual role bindings