Single Sign-On (SSO)

Overview

Realm supports Single Sign-On (SSO) with your identity provider (IdP), such as Okta or Microsoft Entra ID. With SSO, users sign in to Realm with their corporate credentials, and you can assign Realm roles automatically based on the groups each user belongs to in your IdP.

SSO is configured through the SSO setup portal, which you open from Settings > Authentication.

Prerequisites

1. You must have the Super Admin or Integration Admin role in Realm.
2. You must have administrator access to your IdP so you can create the SSO application and manage its groups.

Configure SSO

1. In Realm, navigate to Settings > Authentication.
2. Open the SSO setup portal.
3. Select your IdP and follow the provider-specific steps shown in the portal to create the SSO application in your IdP and exchange the connection details.
4. Assign the users or groups that should have access to Realm to the SSO application in your IdP.
5. Test the connection with Test sign-in on the SSO screen of the portal, using a user assigned to the application.

Assign Roles with IdP Groups

You can map groups from your IdP to Realm roles so that users receive the correct role when they sign in. Role mappings are managed in the SSO setup portal under Groups and role assignments.

Note: A user who signs in without matching any mapped group is assigned the default role, Analyst. For the full list of roles, see Quick Start.

How Group Matching Works

The Create group form has two fields:

Name: An optional display label for the mapping. It is not used for matching.
IdP Group ID: The group value your IdP sends when a user signs in. This is the only value used for matching.

If IdP Group ID does not exactly match the group value your IdP sends, the mapping fails silently and the user is assigned the default role. A common mistake is to enter the IdP group name in Name and an internal ID in IdP Group ID, or the reverse.

Which Value to Use for IdP Group ID

Enter the group value your IdP actually sends at sign-in. Depending on the IdP and its configuration, this can be a group name or an opaque ID, so check the emitted value rather than assuming either.

IdP	Value to Enter in IdP Group ID	Example
Okta	The group name, as sent in the groups attribute or claim	Integration Admin
Microsoft Entra ID	The group Object ID, not its display name	3f2a6c1e-8b4d-4e9a-9c1f-2d7b5e0a6f31

To confirm the exact value your IdP sends, see Inspect the Group Values Your IdP Sends.

Configure Your IdP to Send Groups

Okta

1. For SAML applications, add a Group Attribute Statement to the Realm SSO application:

   Name: groups
   Filter: A filter that includes every group you plan to map

2. For OIDC applications, copy the Okta group name into IdP Group ID when you create the mapping.

Microsoft Entra ID

1. For SAML applications, add a group claim to the Realm SSO application and set its source attribute:

   Source attribute: Group ID

   This sends each group's immutable Object ID.

2. For OIDC applications, use the Entra group ID in IdP Group ID.

3. If the group claim is set to Groups assigned to the application, assign the groups themselves to the Realm SSO application. Assigning only the user does not cause the user's groups to be sent.

Create a Group Mapping

1. In your IdP, find the group you want to map and copy the value listed in Which Value to Use for IdP Group ID.

2. In the SSO setup portal, open Groups and role assignments and select Create group.

3. Fill in the form:

   Name: An optional label, for example Integration Admins
   IdP Group ID: The value copied from your IdP in step 1

4. Select the Realm role to assign to members of this group.

5. Save the mapping.

6. Sign in to Realm with a fresh SSO sign-in as a member of the group, and confirm that the user has the expected role in Settings > Users.

Note: Roles are calculated at sign-in. After you create or change a mapping, users must sign in again through SSO for the new role to apply.

Fix an Incorrect IdP Group ID

The IdP Group ID cannot be edited after the mapping is created. To correct it:

1. In Groups and role assignments, delete the incorrect mapping.
2. Create a new mapping with the correct IdP Group ID, following the steps in Create a Group Mapping.
3. Ask affected users to sign out of Realm and sign in again through SSO so their role is updated.

Note: Recreate the mapping rather than renaming the group in your IdP. Other applications and policies may reference the group by name, and renaming it can break them.

Troubleshooting

Inspect the Group Values Your IdP Sends

You can see exactly which group values your IdP sent for a sign-in from the SSO setup portal.

1. In the SSO setup portal, open the SSO screen and select Test sign-in.
2. Complete the sign-in with a user who belongs to the group you want to map.
3. Open the matching entry under Sessions.
4. Review the session details, which include the request sent to your IdP and the IdP's response.
5. For SAML connections, find the group values in the response and compare them with the IdP Group ID in your mapping.

Users Receive the Analyst Role Instead of the Mapped Role

The default role on its own does not tell you the cause. A user receives Analyst both when the IdP did not send the group and when the group was sent but no mapping matched it. Compare the IdP response with your mapping to find out which case applies.

1. Inspect the group values for the user's sign-in, following the steps in Inspect the Group Values Your IdP Sends.
2. If the intended group value is present but differs from the IdP Group ID, the mapping does not match. Recreate the mapping with the exact value from the response, following the steps in Fix an Incorrect IdP Group ID.
3. If the intended group value is absent, the IdP did not include it in the group claim. Check the IdP's group claim configuration and filter, following the steps in Configure Your IdP to Send Groups, and confirm that the user is a member of the group.
4. Retest with a fresh SSO sign-in.
5. If the mapping is still not applied, contact Realm Support.