SSO Setup
Configure Single Sign-On (SSO) with your organization's identity provider.
SSO Setup
Configure Single Sign-On (SSO) so your team can log in with their identity provider accounts. Gravity Rail supports Google Workspace, Microsoft Entra ID (Azure AD), Okta, Auth0, and any standards-compliant OIDC provider. SSO simplifies access management and lets you enforce domain-based authentication across your organization.
Prerequisites
Before you begin, ensure you have:
- Organization Owner or Admin role in Gravity Rail
- A registered domain owned by your organization (e.g.,
yourcompany.com) - Access to your identity provider's admin console (to create/register an application and copy credentials)
How SSO Works
When SSO is enabled for your organization:
- Users visit your organization's login page (
/o/{your-org}/login, or directly at{your-org}.o.gravityrail.com). - They click the Sign in with {provider} button.
- Your identity provider authenticates them with their corporate account.
- Gravity Rail validates the returned token, checks the email domain against your SSO domain, and (for Entra) verifies the tenant.
- If auto-provisioning is enabled, new users get an account automatically. Otherwise, an existing Gravity Rail account must already be linked.
Supported Providers
| Provider | OAuth / OIDC Route | Provider-specific details |
|---|---|---|
| Google Workspace | Google OAuth | Single-domain workspace validation via Google's hd claim |
| Microsoft Entra ID (Azure AD) | OIDC | Tenant pinning via expectedTenantId; multi-tenant requires domain allowlist |
| Okta | OIDC | Standard OIDC discovery |
| Auth0 | OIDC | Standard OIDC discovery |
| Generic OIDC | OIDC | Any provider publishing .well-known/openid-configuration |
The OIDC callback URI is the same for every OIDC provider:
https://api.gravityrail.com/oauth/oidc/callback
Provider-specific setup steps live further down in this guide.
Enabling SSO
Contact your Gravity Rail account representative to enable SSO for your organization. They will need:
| Information | Example | Purpose |
|---|---|---|
| Organization slug | acme-corp | Identifies your organization |
| Provider | google_workspace / azure_ad / okta / auth0 / generic | Identity provider type |
| SSO domain | acme.com | Email domain to restrict access |
| authMode | open / ssoForDomain / ssoOnly | Organization authentication policy (see below) |
| Auto-provisioning | Yes / No | Auto-create accounts for new users |
| Default role | Member | Role assigned to auto-provisioned users |
| Provider credentials | See per-provider sections | Issuer URL, Client ID, Client Secret, etc. |
Once configured, your organization's login page will display the identity provider sign-in button.
Authentication Modes
The authMode setting controls how strictly SSO is enforced for your organization. Pick the mode that matches your security posture:
authMode | Behavior |
|---|---|
open | Both SSO and standard email/password login are available. Best for gradual rollouts. |
ssoForDomain | Users whose email matches the configured SSO domain must use SSO. Members on other domains can still use standard login. |
ssoOnly | All organization access must go through SSO. Email/password and phone login are disabled for your organization. |
ssoOnly — Enforced SSO
When authMode is ssoOnly:
- The login page only shows the organization's SSO button.
- Email/password and phone login are disabled for your organization.
- All users must authenticate through the configured identity provider.
- Users who previously logged in with other methods must switch to SSO.
This is recommended for organizations that want to enforce centralized identity management.
Domain Validation
When SSO is configured with a domain (e.g., acme.com):
- Only users with
@acme.comemail addresses can sign in via SSO. - Users with other email domains are rejected with the message: "Email domain must be @acme.com to sign in."
- The identity provider must confirm the user's email address is verified.
This ensures only members of your organization's domain can access your workspaces.
Auto-Provisioning
Auto-provisioning controls what happens when someone signs in via SSO for the first time and doesn't already have an account.
With Auto-Provisioning Enabled
- A new account is created automatically from their identity provider profile (name, email, avatar).
- They are added to your organization with the configured default role (typically Member).
- No manual invitation or account creation is needed.
- They can immediately access workspaces they've been granted access to.
With Auto-Provisioning Disabled
- Users who don't have an existing account are rejected.
- They see the message: "Account not found. Please contact your organization administrator."
- An admin must manually create their account or send an invitation before they can sign in.
Disable auto-provisioning if you want to control exactly who has access to your organization.
Role Mapping
Role mapping determines what organization role is assigned to auto-provisioned users:
| Mapped Role | Organization Permissions |
|---|---|
| Member | Access assigned workspaces only |
| Admin | Manage members, workspaces, and invitations |
| Owner | Full control including billing and organization deletion |
The default role for new SSO users is Member. Contact your account representative to configure a different default role.
Note: SSO can assign up to the Owner role at the organization level. System-level superuser access cannot be granted through SSO.
Existing Accounts
If a user already has a Gravity Rail account with the same email address:
- SSO login links to their existing account (no duplicate is created).
- Their profile picture is updated from the identity provider if they don't already have one.
- Their email is marked as verified.
- They retain all existing workspace memberships and roles.
Multi-Organization Access
Users can belong to multiple organizations. If SSO is enabled for one organization but not another:
- They use SSO to access the SSO-enabled organization.
- They use their preferred login method for other organizations.
- Switching between organizations is seamless from the organization switcher.
Provider-Specific Setup
Each provider has its own app-registration steps on the provider side. The steps below cover what to register with the provider and what to send to your Gravity Rail account representative.
Google Workspace
Configure SSO with Google Workspace using Google OAuth.
Prerequisites
- Organization Owner or Admin role in Gravity Rail.
- A Google Workspace domain (e.g.,
yourcompany.com). - Access to your Google Workspace admin console (for verifying domain ownership).
What Gravity Rail Needs
- Provider:
google_workspace - SSO domain: your Google Workspace domain (e.g.,
acme.com)
Google Workspace doesn't require an app registration on the customer side — Gravity Rail's Google OAuth client handles the handshake and uses Google's hd (hosted domain) claim to enforce the domain match.
Troubleshooting
- "Email domain must be @example.com to sign in" — You're signing in with a personal Gmail account or a different Google Workspace domain. Use your corporate Google Workspace account.
- "Your Google account email is not verified" — Google reports the email isn't verified. This is unusual for Google Workspace; check the account settings with your Google Workspace admin.
Microsoft Entra ID (Azure AD)
Configure SSO with Microsoft Entra ID using OIDC.
Prerequisites
- Organization Owner or Admin role in Gravity Rail.
- Access to the Microsoft Entra admin center to register an application.
Callback URI to Register
Register this exact redirect URI with your Entra app:
https://api.gravityrail.com/oauth/oidc/callback
Required Fields
- Issuer URL: e.g.
https://login.microsoftonline.com/{tenant}/v2.0(or the multi-tenant authority) - Client ID: Application (client) ID from Entra
- Client Secret: Client secret value (create one in Entra; encrypted at rest in Gravity Rail)
- Expected Tenant ID (recommended for single-tenant): the directory (tenant) ID to pin to
- Multi-Tenant (optional): toggle to accept tokens from any Entra tenant — requires an SSO domain allowlist
See Microsoft Entra docs for provider-side app registration.
Troubleshooting
- The issuer URL must use HTTPS and be reachable from the public internet.
- If your issuer URL contains the
{tenantid}template, you must either pinexpectedTenantIdor enable Multi-Tenant mode. Otherwise the configuration is rejected because it would accept tokens from any Entra tenant. - Multi-tenant configuration requires a configured SSO domain allowlist.
Okta
Configure SSO with Okta using OIDC.
Prerequisites
- Organization Owner or Admin role in Gravity Rail.
- Access to the Okta admin console to create an OIDC app.
Callback URI to Register
https://api.gravityrail.com/oauth/oidc/callback
Required Fields
- Issuer URL: your Okta domain, e.g.
https://your-org.okta.com - Client ID
- Client Secret
See Okta OIDC docs for application setup.
Troubleshooting
- Ensure scopes include
openid,profile, andemail(defaults are used if omitted). - Verify the issuer URL has no trailing slash.
Auth0
Configure SSO with Auth0 using OIDC.
Prerequisites
- Organization Owner or Admin role in Gravity Rail.
- Access to the Auth0 dashboard to create an application.
Callback URI to Register
https://api.gravityrail.com/oauth/oidc/callback
Required Fields
- Issuer URL: e.g.
https://your-tenant.auth0.com/ - Client ID
- Client Secret
See Auth0 docs for application configuration.
Troubleshooting
- Confirm the issuer matches your Auth0 tenant exactly.
Generic OIDC
Configure SSO with any standards-compliant OIDC provider (Keycloak, Ping, OneLogin, etc.).
Prerequisites
- Organization Owner or Admin role in Gravity Rail.
- Access to your identity provider's admin console.
Callback URI to Register
https://api.gravityrail.com/oauth/oidc/callback
Required Fields
- Issuer URL: base URL of the OIDC issuer (must support discovery or provide endpoint overrides)
- Client ID
- Client Secret
Troubleshooting
- The provider must publish a
.well-known/openid-configurationdocument, or you must supply endpoint overrides via the admin API. - All OIDC URLs must use HTTPS and be publicly reachable.
Troubleshooting
"Email domain must be @example.com to sign in"
Your identity provider account email doesn't match the SSO domain configured for this organization. Sign in with an account on the configured domain.
"Account not found. Please contact your organization administrator"
Auto-provisioning is disabled, and you don't have an existing account. Ask your organization admin to create your account or send you an invitation.
"SSO not configured"
SSO hasn't been set up for this organization yet. Contact your organization admin or Gravity Rail account representative.
"Your email is not verified"
Your identity provider reports that your email address hasn't been verified. Check your account settings with your provider's admin, or see the provider-specific troubleshooting above.
I can't log in with my password anymore
If your organization has authMode set to ssoOnly, password and phone login are disabled. Use your organization's SSO button instead.
I'm locked out of my identity provider and need to access my organization
Contact your organization admin. They can:
- Temporarily set
authModeto a less restrictive value (if they have access) - Contact Gravity Rail support for assistance
Security Notes
- SSO authentication is logged for compliance and audit purposes.
- Email verification is required from the configured identity provider before access is granted.
- Client secrets are encrypted at rest.
- SSO tokens are separate from global session tokens, providing per-organization authentication proof.
- All SSO traffic uses encrypted HTTPS connections.
- For Entra ID, the
{tenantid}template in the issuer URL must be pinned withexpectedTenantIdor explicitly marked as multi-tenant. - Multi-tenant Entra configuration requires an SSO domain allowlist.