Learn how to use SSO claim mappings to automatically assign roles and teams in the Grepr platform when users sign in.

# Manage SSO claim mappings in the Grepr platform

SSO claims mapping lets you automatically assign organization roles and team memberships to users when they sign in through your identity provider (IdP). Using claims mapping, you can reduce the need to manually manage access, and ensure that Grepr access is aligned with your IdP.

You manage SSO claim mappings in the Grepr UI. This page explains how claim mappings work, how to create them, and how they affect user access.

> You must have access to the **User management** page to view SSO claim mappings. To create, edit, or delete mappings, you must have permission to edit organization settings.

## How SSO claim mappings work

When a user signs into Grepr through SSO, Grepr reads the claims passed from the IdP and evaluates them against the claim mappings configured for your organization. When the user first signs in through SSO and after the claims mapping evaluation runs, the IdP becomes the source of truth for that user's organization role and team membership assignments. on subsequent sign-ins through SSO, Grepr makes any necessary updates to ensure that the user's organization role and team membership assignments match the result of claim mapping evaluation based on the current mappings and claims at sign-in time.

If a mapping matches, Grepr assigns the roles and team memberships configured in that mapping.

If multiple mappings match, Grepr combines all assigned organization roles and team memberships from the matched mappings.

Roles and team memberships are not assigned by Grepr if no claims are found in the token sent by the IdP or if your organization does not have any SSO claim mappings configured.

## Access the SSO mappings page

To open the SSO mappings page in the Grepr UI:

1. Sign in to the Grepr UI and click your profile icon in the top bar.
2. In the menu, select **User management**.
3. On the **User management** page, click **SSO Mappings** in the left pane to display the **SSO Claim Mappings** page. The **SSO Claim Mappings** page displays the configured claim mappings for your organization, including the claim key, claim value, assigned roles, and assigned team memberships.

## Create an SSO claim mapping

To create an SSO claim mapping:

1. Go to the **SSO Claim Mappings** page.
2. Click **Create Mapping**.
3. In the **Create Claim Mapping** dialog, enter a **Claim Key**.
4. Enter the **Claim Value** to match.
5. In **Role Assignment**, select one or more organization roles to assign when the claim matches.
6. In **Team Assignments**, click **Add Team** to assign one or more teams and team roles.
7. Click **Create Mapping**.

You must assign at least one organization role or one team assignment in each mapping.

## Edit an SSO claim mapping

To edit an existing SSO claim mapping:

1. Go to the **SSO Claim Mappings** page.
2. Find the mapping you want to update.
3. Click **Edit**.
4. Update the claim key, claim value, roles, or team assignments.
5. Click **Save Changes**.

The updated mapping is used the next time a user signs in through SSO.

## Delete an SSO claim mapping

To delete an SSO claim mapping:

1. Go to the **SSO Claim Mappings** page.
2. Find the mapping you want to remove.
3. Click **Delete**.
4. In the confirmation dialog, click **Delete**.

After you delete a mapping, Grepr no longer uses it during sign-in.

## Understand claim matching behavior

Grepr supports the following claim matching behavior:

* String claims are matched by exact value.
* List claims are matched when the configured claim value appears in the list.
* Map claims are matched by comparing the full map value as a JSON string.

For the most predictable results, use simple custom claims with string or list values when possible.

Grepr does not allow mappings for reserved Java Web Token claim keys such as `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, and `jti`.

## Examples

| Claim key | Claim value | Result |
| --- | --- | --- |
| `department` | `engineering` | Assign the configured roles and teams to users whose `department` claim is `engineering`. |
| `groups` | `platform-admins` | Assign the configured roles and teams to users whose `groups` claim includes `platform-admins`. |
| `realm_access` | `{"roles":["admin","developer"]}` | Assign the configured roles and teams only when the full map value matches this JSON structure. |

## Best practices

* Start with a small set of pilot users before applying mappings broadly.
* Use claims that you define and manage in your identity provider instead of provider-defined claims that might vary by platform.
* Use string or list-valued claims when possible, because they are easier to configure and review.
* Review claim mappings whenever you change role names, team structure, or identity provider claim configuration.
* Document which identity provider groups or attributes are expected to map to Grepr access.

## Frequently Asked Questions

### What happens if multiple SSO claim mappings match the same user?

Grepr combines the organization roles and team assignments from all matched mappings.

### What happens if no mappings match a user?

If claim mapping evaluation runs and no mappings match, Grepr updates the user's assignments to match the empty result. If no token claims are available or no mappings are configured, Grepr preserves the user's current assignments.

### Can I use array-based claims such as groups?

Yes. If the claim value is a list, Grepr matches when the configured claim value appears in that list.

### Can I match part of a nested JSON claim?

Not directly. For map-valued claims, Grepr matches the full object as a JSON string.

### Can I use standard JWT claims such as sub or aud?

No. Reserved JWT claims cannot be used for SSO claim mappings.