Configure single sign-on
Single sign-on (SSO) lets members of a Catalyst organization sign in with their company account, through a SAML 2.0 identity provider (IdP) such as Okta, Microsoft Entra ID or Google Workspace. When someone signs in with an email address on your company's domain, Catalyst sends them to your IdP to authenticate. Anyone with an address on another domain signs in as before.
SSO changes how people authenticate, not what they can access. Each person's role still decides what they can do. By default, Catalyst rejects an SSO sign-in from anyone you have not invited. To let people join based on the groups your IdP sends instead, see Map SSO groups to roles.
Prerequisites
- SSO enabled for your organization. SSO is not part of the self-serve plans. Contact Diagrid Support with your company's email domain, for example
example.com. Diagrid enables SSO for your organization and allows that domain. Until then, the Single sign-on page in the console explains that SSO is not enabled. - A global Admin role (
cra.diagrid:admin). Admins scoped to a project cannot manage SSO. See the permission matrix. - Admin access to your IdP, to create a SAML application for Catalyst.
Each email domain can belong to only one SSO connection across Diagrid. If your company already signs in to another Diagrid organization through SSO on the same domain, for example in the Dapr Ops Dashboard, ask Diagrid Support to share that connection with this organization instead of creating a new one.
Create the connection
Catalyst and your IdP each need two values from the other. Keep the console form open while you work in your IdP: the console shows the Callback URL and Entity ID before you save.
- In the Catalyst console, open Identity and Access › Single sign-on and select Add connection.
- Enter a Name for the connection and your company's Email domain, without the
@. The connection type is always SAML 2.0. Do not select Create yet. - In your IdP, create a SAML application for Catalyst. Copy the Callback URL and Entity ID from the console into it. Leave the console open.
- Configure the IdP application to send each user's email address when they sign in. In Okta, add an attribute statement for
user.email, or sign-in fails. - Copy the IdP application's sign-in endpoint into the console, and upload its signing certificate.
- Optionally, add the IdP's sign-out endpoint so that signing out of Catalyst also signs users out of your IdP.
- Select Create.
Your IdP may use different names for these values:
| Catalyst console | Okta | Microsoft Entra ID | Google Workspace |
|---|---|---|---|
| Callback URL | Single sign-on URL | Reply URL (Assertion Consumer Service URL) | ACS URL |
| Entity ID | Audience URI (SP Entity ID) | Identifier (Entity ID) | Entity ID |
| Sign-in endpoint | Identity Provider Single Sign-On URL | Login URL | SSO URL |
| Sign-out endpoint | Identity Provider Single Logout URL | Logout URL | Not supported |
| Signing certificate | X.509 Certificate | Certificate (Base64) | Certificate |
The signing certificate must be a PEM file: a text file that starts with -----BEGIN CERTIFICATE-----. A binary .cer file is not accepted.
If saving fails because the email domain is not enabled, either Diagrid has not enabled that domain for your organization yet, or another SSO connection already uses it. Contact Diagrid Support in both cases.
Invite your users
Invite each person who should sign in through SSO, with the same email address their IdP account uses. See Invite new users.
Invite people before they first try to sign in. A sign-in through your IdP from an email address that has not been invited is rejected. The exception is when the connection has group mappings with Add users automatically turned on and the person is in a mapped group.
Test the connection
- Open a private browser window and go to the Catalyst console.
- Enter the email address of an invited user. Catalyst sends you to your IdP instead of asking for a password.
- Sign in at your IdP.
The first time each user signs in through SSO, they sign in twice. This is expected: the first sign-in links their IdP account to their Catalyst invitation.
When you test several users on one machine, your IdP can silently sign you in as the previous user, because the email address you type in Catalyst only chooses where to send you. Sign out of your IdP, or use a new private window, between users.
Manage the connection
An organization can only have one SSO connection. The SSO page shows its settings, and the callback URL and entity ID to enter in your IdP again if you need them. These two values never change for a connection. If you delete a connection and create a new one, update your IdP application with the new values.
- Edit the connection to update its name or endpoints, to replace the signing certificate, or to change its group mappings. When your IdP rotates its signing certificate, upload the new one in Catalyst at the same time. Sign-ins fail while the two disagree.
- Delete the connection to stop SSO for your domain. Members on that domain can no longer sign in through your IdP. If the connection is shared with another Diagrid organization, deleting it here only removes it from this organization.
Remove access for people who leave
Disabling someone in your IdP stops them signing in through SSO. It does not remove them from your Catalyst organization, and it does not revoke the API keys they created. Remove them from the organization in Catalyst as well, and delete or rotate any keys your automation depends on. Use service accounts for automation, so it does not depend on one person's account.
Next steps
- Give people the right roles in Manage access.
- Keep projects and policies in Git with declarative management.
