SSO (OIDC)
Enterprise single sign-on with OpenID Connect — how it works, provider setup for Okta and Microsoft Entra ID, and how identities are provisioned.
Relay's Enterprise single sign-on lets your members sign in through your own identity provider (IdP). This page covers what SSO does, the one value you register in your IdP (the redirect URI), setup for Okta and Microsoft Entra ID, how an admin configures the connection, and what to expect from identity keying and just-in-time provisioning.
SSO is an Enterprise-plan feature, managed by organization admins and owners. OIDC is the only protocol today; SAML is a later phase. Existing Google sign-in is unaffected — SSO is additive and configured per organization.
SSO on Relay Cloud is available on Enterprise. Contact hello@userelay.sh to enable SSO for your organization. Until it is enabled the login page shows only Google sign-in, plus a note that SSO via OIDC is available on Enterprise.
How it works
A member runs relay login --sso --email you@company.com. (The Relay web login
page has no email field for SSO; it offers Google sign-in.)
Relay looks up the email's domain. If an enabled SSO connection has claimed that domain, Relay redirects the browser to that organization's identity provider (home-realm discovery).
The IdP authenticates the user and redirects back to Relay's single callback URL with an authorization code.
Relay exchanges the code, fully verifies the ID token, and signs the user in — creating or linking their account (see Identity and provisioning).
The per-organization issuer and client credentials live in Relay; the client secret is encrypted at rest per organization. The only thing you register on your side is Relay's redirect URI.
The redirect URI
Every customer registers the same Relay callback URL in their IdP application. It is not a secret and is identical for all organizations:
| Environment | Redirect URI |
|---|---|
| Production | https://api.userelay.sh/auth/oidc/callback |
OIDC requires an exact-match redirect URI, so register it precisely as shown.
Provider setup
Relay is a confidential OIDC client using the authorization code flow with
PKCE. Whatever the provider, you need three things back from it to enter into
Relay: the issuer URL, a client ID, and a client secret. Relay
requests the openid, email, and profile scopes.
Sign-in method: OIDC - OpenID Connect. Application type: Web Application. Click Next.
Sign-in redirect URIs: add the redirect URI for your environment from the table above.
Assignments: grant the app to the users/groups who should have Relay access, then Save.
From the app's General tab, copy the Client ID and Client secret.
The issuer is your Okta org URL, e.g. https://<your-org>.okta.com (or a
custom authorization-server issuer,
https://<your-org>.okta.com/oauth2/<auth-server-id>). Relay discovers the
endpoints from <issuer>/.well-known/openid-configuration.
Configuring the connection in Relay
In the dashboard, an admin or owner opens Organization → Authentication and uses the SSO (OIDC) card:
Client ID and Client secret — from the provider. The secret is write-only: once saved it is never shown again, and editing other fields without re-entering it leaves the stored secret untouched.
Email domains — the domains this connection owns (e.g. example.com).
Domains are globally unique across Relay; a domain can back only one connection.
Click Test discovery to confirm Relay can reach the issuer and resolve its endpoints before going live.
Toggle Enabled and save. Discovery must succeed and the connection must be enabled before any member can sign in through it.
Identity and provisioning
- Identity key. A user is identified by
(issuer, subject)from the ID token — never by email. The IdP's stable subject is what ties a Relay account to the external identity, so a user changing their email at the IdP keeps the same Relay account. - Claimed-domain requirement. A first-time SSO login is only accepted if the email's domain is claimed by this connection. A token asserting an unclaimed domain is refused, so a misconfigured or hostile IdP cannot mint accounts on domains the organization does not own.
- Auto-link. If a user with the same email already exists in this
organization and the IdP did not assert
email_verified=false, the SSO identity is linked to that existing account. Same-email accounts in other organizations are never touched (email is unique only per organization). - Just-in-time provisioning. A genuinely new user is created in the connection's organization and joins as a member — no separate personal organization and no sample database are created.
Troubleshooting
If sign-in fails, the browser returns to the login page with an ?error= code:
| Error code | Meaning | Fix |
|---|---|---|
sso_not_configured | No enabled connection claims the entered email's domain. | Confirm the domain is listed on the connection and the connection is enabled. |
sso_unavailable | Relay could not reach or discover the issuer at login start. | Check the issuer URL and IdP availability; re-run Test discovery. |
sso_denied | The IdP returned an error (user declined consent, or is not assigned the app). | Assign the user/group to the IdP application. |
sso_disabled | The connection was disabled between starting and finishing login. | Re-enable the connection. |
sso_domain_mismatch | The verified email's domain is not claimed by this connection. | Add the domain to the connection, or have the user sign in with an address on a claimed domain. |
sso_account_conflict | An account with this email already exists and is bound to a different identity from the IdP. | Contact Relay support; the existing account has to be resolved before the user can sign in with SSO. |
Token-verification failures (bad signature, wrong audience, expired token, nonce/state mismatch) surface an error at the callback rather than a redirect; these indicate an IdP misconfiguration (wrong client ID/secret, clock skew).