SSO Setup
To allow Gmail, Calendar, Drive, or Sheets connections on a managed Google domain, follow Google Workspace Accounts. Those connector permissions are configured separately from sign-in.
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 | Email-domain validation on sign-in; Google's account chooser offers accounts in the SSO domain |
| 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
Open your Organization and select Single Sign-on under Settings. In Provider, select Google Workspace or OpenID Connect. For OpenID Connect, select Microsoft Entra ID, Okta, Auth0, or Generic OIDC in Provider type. Enter the configuration and select Save changes. To remove SSO, select None and then Save changes.
Your Gravity Rail account representative can help with setup using the following information:
| Information | Example | Purpose |
|---|---|---|
| Organization slug | acme-corp | Identifies your organization |
| Provider | Google Workspace / OpenID Connect | Sign-in protocol |
| Provider type | Microsoft Entra ID / Okta / Auth0 / Generic OIDC | Shown for OpenID Connect |
| 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.
Require multi-factor authentication
Organization Owners and Admins can require multi-factor authentication (MFA) for interactive access to their organization and its Workspaces.
- Sign in with a passkey and complete its device verification, or complete a second factor after another sign-in method. If you use OIDC, your identity provider must send evidence of MFA.
- Open your Organization and select Basic Settings under Settings.
- Turn on Require multi-factor authentication and select Save changes.
The setting is off by default for existing and new organizations. Ordinary Admin and Owner actions follow this setting and do not require MFA while it is off. Turn it on if your organization wants to require MFA for interactive access. People may need to sign in again after the policy changes. Changing the setting in either direction requires an interactive sign-in with completed MFA; integration credentials cannot change it or the SSO configuration. Creating an organization API key still asks for a fresh MFA ceremony, separate from this setting. A device-verified passkey or a completed second factor satisfies that ceremony.
Google Workspace SSO cannot provide the MFA evidence Gravity Rail needs for
this setting. If your organization requires Google SSO, configure an OIDC
provider that supplies MFA evidence before turning the setting on. Gravity
Rail will reject the incompatible combination.
When Google SSO is configured in open mode, the combination is allowed, but
Google sign-in alone cannot satisfy the MFA requirement. Use an account sign-in
with a device-verified passkey or a completed second factor for access, or
configure an OIDC provider that supplies MFA evidence. A passkey does not
replace SSO when your organization requires it.
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: "Your email address is not authorized for this organization."
- 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, and their identity provider has verified that 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.
Some identity providers send a sign-in name rather than a verified email address (for example, Microsoft Entra ID). Those sign-ins are not linked to an existing account by email. Instead, the user signs in with an identity that belongs to your organization only, separate from their existing account. If automatic provisioning is turned off, the sign-in is refused.
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 enter on the Single Sign-on page. Contact your Gravity Rail account representative if you need help.
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. Google's account chooser offers accounts in your SSO domain, and Gravity Rail admits a sign-in only when its email address is in that domain.
Troubleshooting
- "Your email address is not authorized for this organization." — 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.
Google Workspace sign-in is not the same as connecting Gmail, Calendar, Drive, or Sheets. Login only asks Google who you are. Those connectors ask for the mailbox, calendar, or files, and many domains block that until an admin allowlists Gravity Rail. See Google Workspace Accounts.
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
"Your email address is not authorized for this organization."
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.