Skip to main content
Single sign-on (SSO) allows users to sign in to Orion through your identity provider instead of using an Orion password. Invitations from User Management create accounts one at a time. An SSO provider authenticates users and creates an account when no matching Orion account exists. Allowed domains and optional group mappings determine who can complete sign-in. Orion supports compatible identity providers that publish an OpenID Connect discovery document, issue RS256-signed ID tokens, and support an authorization code exchange with a client secret. Register Orion as an application with your provider, then enter its issuer, client ID, and client secret in Orion. You also choose the provider name shown on the login page. Orion uses the issuer to discover the authorization endpoint, token endpoint, and signing keys.

​
Before you start

Create an OAuth application in your identity provider first. Orion uses the authorization code flow and requests the openid, email, and profile scopes. Register this redirect URI on that application:
Identity providers name that field differently. Look for a redirect URI, a callback URL, or a sign-in redirect URI. Save these three values for the setup in Orion: Your identity provider must report the user’s email address as verified. Orion rejects a sign-in when the token does not confirm this, because an unverified address could belong to another user. Create any Groups you plan to assign through SSO before you configure the provider. The mapping editor only lists groups that already exist.

​
Accessing SSO Configuration

Only tenant Admins can access SSO Configuration. A group administrator without the tenant Admin role cannot open it.
  1. Open Configuration in the left-hand navigation menu
  2. Select SSO Configuration in the Admin Settings sidebar
When no providers exist, the page shows No SSO Providers Configured and one button: Add Your First OIDC Provider.
On a shared trial tenant the SSO Configuration entry appears but stays disabled. Sign-in providers are configured per tenant, and a trial tenant is shared with other companies.

​
Adding an OIDC provider

  1. Click Add OIDC Provider, or Add Your First OIDC Provider for the first one
  2. Enter a Provider Name. The login page displays it after Continue with, so choose a name users will recognize
  3. Enter the OIDC Issuer URL, OAuth Client ID, and OAuth Client Secret
  4. List the domains you admit under Allowed Email Domains, pressing Enter, Tab, or comma after each one
  5. Click Create Provider
The Add OIDC Provider dialog, showing the Provider Name, OIDC Issuer URL, OAuth Client ID and OAuth Client Secret fields in order, then a blue OAuth Application Setup panel carrying the redirect URI, above the Cancel and Create Provider buttons

Example OIDC provider configuration

A new provider is enabled as soon as you create it. Its sign-in button can take up to five minutes to appear on the login page. Once it appears, users who meet the allowed-domain and group-mapping rules can sign in.
Leaving Allowed Email Domains empty admits every domain your identity provider will authenticate. Add the domains you own before you create the provider, not afterwards.
Portal Visitor Domains and Enable Provider are available only in the Configure dialog. Create the provider, then open Configure to set them.

​
Restricting who can sign in

Allowed Email Domains controls which email domains are eligible to sign in. Orion rejects other domains before creating or reusing an account and tells the user to contact their administrator. Users at an allowed domain can sign in without an invitation if they also satisfy any group mappings. Only add domains you control. Orion highlights allowed domains that are not also portal visitor domains in an amber notice. Review this notice for domains that should have portal-only access.

​
Portal visitor domains

A portal visitor can only open pages shared with them. To give external users portal-only access, add their domain to both Allowed Email Domains and Portal Visitor Domains in Configure. If Allowed Email Domains is empty, add the domain only to Portal Visitor Domains, but remember that every domain your provider authenticates remains eligible to sign in. New users from allowed domains that are not on the visitor list receive Viewer accounts. Existing Orion accounts keep their current tenant role.

​
Mapping domains or claims to groups

Open Configure for the provider. The Group Assignment section offers two options: Map domains to groups and Map claims to groups. Both create a table where each row defines a value, Group, and Role. Map domains to groups uses the hd claim. When a provider omits hd, Orion derives the value from the user’s verified email domain. For other values, use Map claims to groups and enter a Claim Name the provider sends, such as groups or department.
The Claim-to-Group Mapping card with Claim Name set to groups, then two rows: claim value analytics mapped to the Analytics group as Analyst, and finance mapped to the Finance group as Viewer, with an Add mapping button below

Example claim-to-group mappings

Role controls what the user can do inside that group: Admin, Analyst, or Viewer. It does not change their tenant role. See Groups for a comparison of all six roles. Orion checks the mappings at every sign-in. If a user’s claim value no longer matches, Orion removes the membership created by that mapping. It never changes or removes memberships added manually by an administrator.
Once mappings exist, every user’s token must match at least one row. Orion rejects the sign-in when no row matches. Add a row for every expected claim value, or remove the mapping.

​
What happens when a user signs in

When no matching Orion account exists, the first sign-in creates one. New users from a portal visitor domain receive the Visitor tenant role. All other new users receive the Viewer tenant role. Later sign-ins never change that tenant role. Change tenant roles from Manage Users when users need more access. Group memberships managed through SSO are refreshed at every sign-in. If the email address matches an existing Orion account, Orion reuses that account and keeps its current role. Email matching ignores letter case.
Password sign-in stays available alongside your SSO buttons. Ask your Gravity contact if you want the login page to offer single sign-on only.

​
Enabling, testing, and deleting a provider

Each provider row includes Configure, a Details accordion, and an Enabled or Disabled badge. Expand Details to view the issuer, a truncated client ID, and two actions.
  • Configure edits everything, including the Enable Provider switch. Leave OAuth Client Secret empty to keep the secret you already stored.
  • Test Connection confirms that the provider record exists and is enabled. It does not perform a sign-in or validate credentials. The button is unavailable while a provider is disabled.
  • Delete Provider asks for confirmation, then removes the provider.
The SSO Configuration screen reached from the Admin Settings sidebar, with one provider named Company SSO carrying an Enabled badge, a Configure button, and an expanded Details panel showing its issuer and a truncated client ID. Test Connection is outlined in red, beside a red Delete Provider button

Example configured SSO provider

Turning Enable Provider off preserves the configuration and removes the provider’s button from the login page.
Deleting a provider cannot be undone. Its allowed domains, portal visitor domains, and group mappings go with it, and users cannot sign in through it again. Accounts and group memberships created through it stay exactly as they are.

​
When a change takes effect

Provider changes can take up to five minutes to appear on the login page, because it caches the list of enabled providers for five minutes. This delay applies when you add, rename, enable, or disable a provider. Domain rules and group mappings apply at the next sign-in. They do not affect existing sessions.

​
Troubleshooting

When Orion rejects a sign-in, it displays the reason and tells the user to contact their administrator: If sign-in fails after Test Connection passes, check the redirect URI, client secret, and scopes on the OAuth application. If a change locks every administrator out of your tenant, contact Gravity support.

​
Next Steps

Groups

Create the groups your claim mappings assign, and see what each group role can reach

User Management

Set tenant roles, invite the users your provider does not cover, and audit who has access