Map SSO groups to roles

Once single sign-on is set up, you can give roles to the groups your identity provider (IdP) sends when someone signs in, instead of setting roles for each person by hand. You can also let anyone in a mapped group join your organization the first time they sign in, with no invitation.

This works with any SAML 2.0 IdP that can send group membership. This page shows the Catalyst console and the steps for Microsoft Entra ID. The Dapr Ops Dashboard has the same Groups section on its SSO connection, with its own Admin, Editor and Viewer roles.

How it works

• Your IdP sends the user's groups in a SAML attribute. You tell Catalyst the attribute's name.
• A mapping says which roles one group gets. Roles can apply to the whole organization or to one project, the same as when you invite a user. Someone in several mapped groups gets all of their roles.
• Every time someone signs in through SSO, Catalyst reads their groups again and works out their group roles from scratch. Roles you gave by hand never change. The users list shows which roles came from a group and which you gave directly.
• Group changes take effect the next time the person signs in, not right away. To remove someone now, remove them from the organization as you do today.
• People who join through a group take a seat, like invited members. When no seat is free, their sign-in is refused with a "seat limit reached" message.

Prerequisites

• An SSO connection for your organization. See Configure single sign-on.
• A global Admin role (cra.diagrid:admin).
• Admin access to your IdP, to add a groups attribute to the SAML application you created for Catalyst.

If your SSO connection is shared with another Diagrid organization, neither organization can change the groups attribute. Ask Diagrid Support to set it.

Send groups from your IdP

Set up the SAML application you use for Catalyst so it sends the user's groups as an attribute. Note the attribute's name and what its values look like. If your IdP can send a group ID instead of a name, use the ID. Names can change or be reused.

Microsoft Entra ID

Entra sends groups in the attribute http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. Each value is a group's object ID.

1. In the Microsoft Entra admin center, open Enterprise applications and select the application you created for Catalyst.
2. Open Single sign-on › Attributes & Claims › Edit, then select Add a group claim.
3. Under Which groups associated with the user should be returned in the claim?, choose Groups assigned to the application.
4. Leave Source attribute as Group ID and save.
5. Open Users and groups › Add user/group and assign every group you plan to map. Entra only sends the groups you assign here.
6. For each group you will map, copy its Object ID from Groups in the admin center.

Entra sends at most 150 groups in a SAML sign-in. If someone is in more groups than that and the application sends all of them, Entra leaves the groups out and that person gets no roles from groups. Groups assigned to the application avoids this, because only the assigned groups are sent.

Add the mappings in Catalyst

1. In the Catalyst console, open Identity and Access › Single sign-on and find the Groups section of your connection.
2. In Groups attribute, enter the attribute name exactly as your IdP sends it. For Entra, that is http://schemas.microsoft.com/ws/2008/06/identity/claims/groups.
3. Select Add mapping. Enter the Group value exactly as it appears in the attribute (for Entra, the group's object ID), an optional Display name, and the roles the group gets. Select Add.
4. Repeat for each group. You can map each group value once.
5. Choose whether to turn on Add users automatically. It is off by default.
   • Off: mappings only add roles to people you have invited. Use this to try a mapping safely.
   • On: someone who signs in through SSO and is in a mapped group joins the organization without an invitation, if a seat is free.
6. Select Save groups.

If a mapping gives an admin role, Catalyst asks you to confirm before saving. Everyone your IdP puts in that group becomes an admin the next time they sign in.

Test a mapping

1. Add a test user to one mapped group in your IdP.
2. In a private browser window, sign in to the Catalyst console as that user.
3. In Identity and Access › Users, check that the user is listed and that the Granted by column shows SSO group for the roles you expect.

Someone who is already signed in keeps their old roles until they sign in again.

What happens at sign-in

Situation	Result
Someone in a mapped group signs in for the first time, with Add users automatically on	They join with the group's roles.
Same, with Add users automatically off	Refused as not invited. Invite them, or turn on Add users automatically.
Someone is in no mapped group and was never invited	Refused as not invited.
Someone joins or leaves a mapped group	Their roles change the next time they sign in.
Someone who joined through a group is no longer in any mapped group	They can no longer sign in. They stay in the users list until you remove them.
Someone also has roles you gave directly	Group changes never touch those roles.
The organization has no free seat	New people are refused. Existing members are not affected.

A group value has to match what your IdP sends character for character. Catalyst only uses the groups sent by the SSO connection the person signed in through, and only the mappings you set for your organization.