Skip to main content

​
Single sign-on (SAML and OIDC)

Single sign-on lets your team sign in to Gradient with the account they already have at work. Your identity provider decides who has access, and it can also decide what role each person holds. Gradient supports SAML 2.0 and OIDC, with ready-made options for Okta, Microsoft Entra ID, and Google Workspace, plus a custom option for any other provider.
Single sign-on is an enterprise feature. If you do not see Settings, Identity and SSO, contact your Gradient representative to turn it on for your organization.

​
What you need

  • A Gradient owner account. Identity settings are owner-only.
  • An administrator account at your identity provider, with permission to create applications.
  • About 20 minutes, plus the time your identity team needs to send you their metadata.
You do not have to finish in one sitting. A connection you create stays in a pending state until the metadata exchange is complete, and a pending connection cannot sign anyone in. Nothing changes for your team until you finish.

​
Choosing between SAML and OIDC

Both protocols sign people in equally well. They differ in where Gradient roles can come from, and that is the whole decision.
An OIDC connection cannot map groups to roles. This is a limit of our identity platform, not of the protocol, and the role assignment controls do not appear at all on an OIDC connection. If you want OIDC and directory-driven roles, plan for directory sync (SCIM) at the same time.

​
Part 1: Create the connection in Gradient

  1. In Gradient, go to Settings, Identity and SSO.
    The Identity and SSO entry in the Gradient settings menu

    Settings, Identity and SSO

  2. On the Single sign-on card, click New connection. Choose your identity provider and protocol, then give the connection a display name your team will recognize, for example “Acme (Okta)”.
    The Single sign-on card with the New connection button highlighted

    The Single sign-on card, before any connection exists

    The list offers Okta and Microsoft Entra ID in both protocols, Google Workspace in SAML, and a custom option for each protocol.
  3. Copy the values Gradient shows. They differ by protocol:

​
Part 2: Set up the application in your identity provider

Do this in your identity provider, or send the values to the team that administers it.

​
If you chose SAML

  1. Create a new SAML application for Gradient.
  2. Paste the ACS URL and the SP Entity ID from Part 1 into the application.
  3. Set the name ID to the user’s email address. Gradient identifies people by email.
  4. Save the application, then collect three values from it: the IdP Entity ID, the IdP SSO URL, and the X.509 signing certificate.
  5. Back in Gradient, paste those values into the connection and save.
Record the expiry date of the SAML signing certificate now, and set a reminder 30 days before it. An expired certificate stops every sign-in for your organization at once. See Plan for lockout.

​
If you chose OIDC

  1. Create a new OIDC web application for Gradient, with the authorization code grant type.
  2. Set its sign-in redirect URI to the Redirect URI from Part 1.
  3. Save the application, then collect three values: the Client ID, the Client Secret, and the Issuer.
  4. Back in Gradient, paste those three values into the connection and save. Gradient reads the rest of the endpoints from your issuer automatically, so there is nothing else to copy.
OIDC has no certificate to expire, which removes the most common cause of a sudden organization-wide sign-in failure. Either way, the connection becomes active once the details are complete. Until then it stays pending and cannot sign anyone in.

​
Part 3: Map your groups to Gradient roles

Your identity provider can set each person’s Gradient role from their directory group. This keeps permissions in one place: you change someone’s group, and their Gradient access follows. How you do it depends on the protocol you chose.

​
With SAML

  1. Configure your identity provider to send a groups claim on the assertion.
  2. In Gradient, go to Settings, Identity and SSO and scroll to Automatic Role assignments. Click Edit, and map each group to one Gradient role. The same card also grants roles by email domain or by SSO connection, if you would rather not use groups.
    The Automatic Role assignments card with its Edit button highlighted

    Automatic Role assignments, at the bottom of the page

​
With OIDC

Set up directory sync (SCIM) and map your groups there. SCIM group mapping works whichever protocol people sign in with, so an OIDC organization gets the same directory-driven roles a SAML one does. Without SCIM, an OIDC connection cannot take roles from your directory. Grant them by email domain on the same Automatic Role assignments card, or set each person’s role at Settings, Team. Use the role names exactly as written, in lower case: A group change in your identity provider reaches Gradient within about five minutes. A new sign-in is always current, so ask the person to sign out and in again if they need the change immediately.

​
Part 4: Test one sign-in before you enforce

Do not turn on enforcement until one real person has signed in through the connection.
1

Pick one pilot user

Someone in a mapped group who is not you. Keep your own session signed in on another browser so you can undo any mistake.
2

Have them sign in

Send them your organization sign-in link, described in Sign-in links.
3

Check the result

Open Settings, Team. The pilot user should appear with the role their group maps to. If the role is wrong, fix the group mapping and have them sign in again.

​
Part 5: Require SSO for everyone

Once a real sign-in works, you can turn off the other ways in. All of these live on Settings, Identity and SSO, in the Authentication policy card. Each block has its own Edit button. Enforcement is only complete when all three agree. Your security team will ask about each one.
The Authentication settings block with the Edit button and the Allow all primary auth methods toggle highlighted

Authentication settings: 1 opens the block for editing, 2 is the switch that allows every sign-in method

The User onboarding block with the JIT provisioning checkboxes and the Allowed SSO connections option highlighted

User onboarding: 1 and 2 control who may join without an invitation, 3 limits joining to your own connection

Email-domain joining appears in two places. Settings, Team has the plain Auto-join by email domain switch, and this card has the same control as JIT Provisioning, Email domains. They write the same setting, so turning it off in either place is enough. Check both if you are auditing.
Turning auto-join off has a side effect. On the shared sign-in page at app.trygradient.ai/login, Gradient identifies your organization from the email address, and for a person who has never signed in before that lookup depends on domain auto-join. With auto-join off, a new hire sees “no connections found” and no explanation. Give your team the organization sign-in link below, which does not need the lookup at all.
There are two ways to reach the sign-in page, and for an enforced organization only one of them works for everybody. Find your organization link on Settings, Identity and SSO, under Your sign-in link. Copy it and give it to your team, put it in your onboarding documentation, and use it in your identity provider’s application tile. It works as soon as your connection is active, and there is nothing to set up.
The Your sign-in link card with the organization link and the copy button highlighted

Your sign-in link: 1 is the link to share, 2 copies it

Sign-in started from your identity provider’s own application tile also works, and needs neither link.

​
Plan for lockout before you enforce

An enforced organization depends on your identity provider. If that provider has an outage, or a SAML certificate expires, or an OIDC client secret is rotated without telling us, nobody in your organization can sign in. Prepare for it now.
1

Keep one break-glass owner

A named account with the owner role, outside your directory sync, allowed to sign in by email magic link with multi-factor authentication. Set it up at the same time as the connection, not after an incident.
2

Store its recovery codes safely

Put the multi-factor recovery codes in your password manager, not with the person who owns the account.
3

Know how to undo enforcement

The break-glass owner opens Settings, Identity and SSO, and allows all sign-in methods again on the Authentication policy card. Access returns immediately. Contact Gradient support if nobody can sign in at all.
4

Re-enforce after the fix

Turn enforcement back on only after one real sign-in through the identity provider works again.

​
Troubleshooting

They used the shared sign-in page and have never signed in before. Send them your organization sign-in link, app.trygradient.ai/login/your-org.
Check the group mapping on the connection, and check that the person is in the expected group in your identity provider. Role names must be exactly owner, admin, member, or reviewer. After a fix, have them sign out and in again rather than waiting.
Allow about five minutes. A new sign-in applies the change at once.
On a SAML connection, check the signing certificate first. An expired certificate is the most common cause, and it fails for everyone at the same time. On an OIDC connection, check whether the client secret was rotated in your identity provider. Use your break-glass owner to restore access while you fix either one.
Sign in with the break-glass owner and allow all sign-in methods again. If that account cannot sign in either, contact Gradient support.

​
What single sign-on does not do

  • It does not create or remove accounts. SSO authorizes people who reach the sign-in page. To have your directory create, update, and deactivate Gradient members automatically, add directory sync (SCIM) as well.
  • It does not manage members inside Gradient. You still see and manage people at Settings, Team, unless SCIM is turned on, which makes your directory the source of truth.
  • It does not apply to candidates. Candidates never sign in. Their assessment link is their credential, and it is unaffected by your sign-in policy. See Authentication.