Skip to main content
Single sign-on (SSO) lets users sign in through your identity provider. Orion can create an account on the first successful sign-in. Allowed domains and claim assignments control access. Orion supports identity providers that publish OpenID Connect discovery metadata. They must issue RS256-signed ID tokens and support an authorization code exchange with a client secret.

Before you start

Create an OpenID Connect web application in your identity provider. Orion requests the openid, email, and profile scopes. It requests groups when the provider advertises it. Orion requests roles when the provider advertises it and an assignment uses that claim. Register this redirect URI on the application:
Identity providers may call this a redirect URI, callback URL, or sign-in redirect URI. Save these values for Orion: Your identity provider must mark the user’s email address as verified. Orion rejects unverified addresses because they could belong to another user. Create any Groups you plan to assign before configuring the provider. The assignment editor lists groups that already exist.

Open SSO Configuration

Only tenant admins can open SSO Configuration.
  1. Open Admin Settings in the left-hand navigation menu
  2. Select SSO Configuration
When no providers exist, select Add Your First OIDC Provider.

Add an OIDC provider

  1. Select Add OIDC Provider, or Add Your First OIDC Provider
  2. Enter a Provider Name that users will recognize on the login page
  3. Enter the issuer URL, client ID, and client secret
  4. To restrict sign-in by email domain, add each domain under Allowed Email Domains
  5. If Orion should assign access from identity provider claims, add role or group assignments
  6. Select Create Provider
Press Enter, Tab, or comma after each allowed domain. Leaving the list empty allows every domain that your identity provider authenticates.
The Add OIDC Provider dialog with connection settings on the left and access and assignment settings on the right

Add an OIDC provider and choose its access rules

A new provider is enabled when you create it. Its login button can take five minutes to appear.
When your identity provider or access management system supports application assignments, assign the Orion application only to users who should be able to sign in. After authentication, Orion applies its access rules and may create an account without an invitation.

Choose who can sign in

After authentication, Allowed Email Domains is Orion’s first access check. When the list contains values, Orion rejects an address from any other domain before it creates or reuses an account. An empty list skips this check. To restrict access by domain, list only the domains whose users should pass it. Entries in either domain list also match subdomains.

Portal visitor domains

Open Configure to add Portal Visitor Domains. Without account role assignments, a new user from one of these domains becomes a Visitor, while other new users become Viewers. Visitors can open shared pages and do not use a seat. Add an external domain to Portal Visitor Domains when its users only need shared pages. If Allowed Email Domains contains values, add the external domain there too. Configure identifies allowed domains that create Viewer accounts, so you can confirm that they belong to your organization.

Assign account roles and groups

Select Map roles or groups to match identity provider claims at every sign-in. Each row contains a source claim, an exact value, and an Orion target. Use Roles when the token contains a roles claim. Use Groups for a groups claim. Select Other claim for a claim such as department. Claim names and values are case-sensitive. When assignments exist, Orion requires at least one matching row. Conflicting account role matches block sign-in.

Assign an account role

Set Assign to to Orion account role, then choose one of these roles:
  • Portal visitor
  • Viewer
  • Analyst
  • Tenant admin
Account role assignments replace the user’s current account role at each sign-in. A user who matches conflicting account roles cannot sign in. When the configuration includes account role assignments, a user who matches only a group row becomes a Visitor. A group assignment does not give a Visitor access beyond shared pages.

Assign a group

Set Assign to to Orion group membership. Choose an Orion group and a group role of Viewer, Analyst, or Admin. A configuration containing only group assignments preserves an existing user’s account role. New users receive the Visitor or Viewer default from the domain settings. Orion refreshes SSO-managed memberships at each sign-in. Memberships added manually by an administrator take precedence.
Role and group assignments with team-admins mapped to the Tenant admin account role and team-analytics mapped to the Analytics group as Analyst

Example identity provider claim assignments

Google OIDC does not supply role or group claims to this editor. You can still restrict email domains and map a hosted domain to an Orion group.

Use domain or claim group mappings

Use Group Assignment to map one domain or claim to Orion groups. These mappings do not change an account role.
  • Map domains to groups uses the hd claim. Orion derives it from the verified email domain when the token omits it.
  • Map claims to groups matches one claim, such as groups or department.
Each row maps a value to an Orion Group and Role. Orion rejects sign-in when mappings exist and no row matches. It also removes SSO-managed membership after a later sign-in no longer matches. Select Map roles or groups when you need account roles or several source claims. Orion converts existing domain or claim group mappings into the new assignment rows.

Configure Okta

Use your Okta organization URL as the Orion issuer:
In the Okta application, add a groups claim to the ID token. Filter the claim to the groups Orion should receive. Okta supports exact, prefix, substring, and regular expression filters. For example, a Starts with filter of team- returns groups such as team-analytics. Orion must map the complete group name, including the prefix and letter case. See Okta’s groups claim guide for the current claim settings. Users must be assigned to the Okta application. When Orion assignments use Okta group values, the user must also belong to a mapped group. Test with a real sign-in after saving both systems.

What happens at sign-in

At each sign-in:
  1. The identity provider authenticates the user and returns verified identity claims
  2. If configured, Orion checks the user’s email domain against Allowed Email Domains
  3. If configured, Orion checks role or group assignments
  4. Orion creates or reuses the account by case-insensitive email address
  5. Orion reconciles the account role and SSO-managed group memberships
Without account role assignments, existing accounts keep their current role. Portal Visitor Domains determines whether a new user becomes a Visitor or Viewer. With account role assignments, Orion recalculates the account role at every sign-in. Group-only assignments leave an existing account role unchanged.
Password sign-in remains available beside SSO buttons. Inform your Gravity contact if SSO is the only allowed sign-in method so the login page can be updated.

Manage a provider

  • Configure changes connection settings, access rules, assignments, and whether the provider is enabled
  • Test Connection confirms that the provider record exists and is enabled
  • Delete Provider removes the provider after confirmation
Test Connection does not run the browser sign-in flow, validate client credentials, or inspect a user’s claims. Complete a real sign-in to verify the provider configuration and assignments.
Leave OAuth Client Secret empty in Configure to keep the stored secret. Turning off Enable Provider preserves the configuration and removes its login button.
The SSO Configuration page with an enabled provider, expanded details, and the Test Connection button outlined in red

Example configured SSO provider

Deleting a provider cannot be undone. Users can no longer sign in through it. Existing accounts and current group memberships remain in Orion.

When changes take effect

Login page changes can take up to five minutes after you add, rename, enable, or disable a provider. Domain and assignment changes apply at the next sign-in. They do not change an existing session.

Troubleshooting

Use the sign-in error to find the failed check: If Test Connection passes but sign-in fails, check the redirect URI, application assignment, claims, client secret, and scopes. If a change locks every administrator out, contact Gravity support.

Next Steps

After the first SSO sign-ins, review the resulting account roles and group memberships to confirm that they match your assignments.

Groups

Create assignment targets and compare the available group roles

User Management

Review account roles and access across your tenant