SSO Setup
Configure Single Sign-On (SSO) with Google Workspace for your organization.
SSO Setup
Configure Single Sign-On (SSO) so your team can log in with their Google Workspace accounts. 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 Google Workspace domain (e.g.,
yourcompany.com) - Access to your Google Workspace admin console (for verifying domain ownership)
How SSO Works
When SSO is enabled for your organization:
- Users visit your organization's login page (
/o/{your-org}/login) - They click Sign in with Google
- Google authenticates them with their corporate account
- If their email domain matches your configured SSO domain, they're logged in
- If auto-provisioning is enabled, new users get an account automatically
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 |
| SSO domain | acme.com | Email domain to restrict access |
| SSO required | Yes / No | Whether to enforce SSO-only login |
| Auto-provisioning | Yes / No | Auto-create accounts for new users |
| Default role | Member | Role assigned to auto-provisioned users |
Once configured, your organization's login page will display the Sign in with Google button.
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 (e.g.,
@gmail.com) are rejected with the message: "Email domain must be @acme.com to sign in." - Google must confirm that the user's email address is verified
This ensures only members of your organization's domain can access your workspaces.
SSO-Required Mode
When SSO required is enabled:
- The login page only shows the Sign in with Google button
- Email/password and phone login are disabled for your organization
- All users must authenticate through Google Workspace
- Users who previously logged in with other methods must switch to SSO
This is recommended for organizations that want to enforce centralized identity management through Google Workspace.
When SSO is not required, users see both the SSO button and traditional login options. This is useful during a transition period.
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 using their Google 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 Google 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
Troubleshooting
"Email domain must be @example.com to sign in"
Your Google account email doesn't match the SSO domain configured for this organization. Make sure you're signing in with your corporate Google Workspace account, not a personal Gmail account.
"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 Google account email is not verified"
Google reports that your email address hasn't been verified. This is unusual for Google Workspace accounts. Check your Google account settings or contact your Google Workspace admin.
I can't log in with my password anymore
If your organization has SSO required enabled, password and phone login are disabled. Use the Sign in with Google button instead.
I need to access my organization but I'm locked out of Google
Contact your organization admin. They can:
- Temporarily disable SSO-required mode (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 Google before access is granted
- SSO tokens are separate from global session tokens, providing per-organization authentication proof
- All SSO traffic uses encrypted HTTPS connections