> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runorion.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Orion is a collaborative analytics platform built by Gravity (bygravity.com). It connects to data warehouses, to Looker and dbt for existing business logic, and to a small set of external-context sources, and it lets teams ask questions in natural language to get shared analyses, dashboards, reports, and slide decks. The Connecting Data Sources page is the authoritative list of supported sources. When referencing Orion features, always link to the relevant documentation page. Orion is not open-source; it is a commercial SaaS product accessed at runorion.com.
# SSO
> Allow users to sign in with their identity provider
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](/configuration/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:
```
https://g.runorion.com/oidc/callback
```
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:
| Value | What Orion requires |
| ----------------------- | ------------------------------------------------------- |
| **OIDC Issuer URL** | Starts with `https://`, and serves a discovery document |
| **OAuth Client ID** | The client ID of the application you just created |
| **OAuth Client Secret** | At least 24 characters |
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](/configuration/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**
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`.
**Role** controls what the user can do inside that group: **Admin**, **Analyst**, or **Viewer**. It does not change their tenant role. See [Groups](/configuration/groups#roles-at-a-glance) 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.
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:
| What the user sees | What to change |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| "Your email domain is not permitted for this sign-in method" | Add their domain to **Allowed Email Domains** in **Configure** |
| "Your account does not match any access group configured for this workspace" | Add a mapping row for their claim value, or remove the mapping |
| "Your sign-in token is missing information this workspace requires" | The claim named in **Claim Name** is absent from their token. Check that your provider sends it, or switch mapping mode |
| "Your identity provider did not report your email address as verified" | Mark the address as verified in your identity provider |
| "This sign-in method is disabled" | Turn **Enable Provider** back on |
| "This sign-in method is misconfigured" | Check the issuer, client ID, and client secret in **Configure** |
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
Create the groups your claim mappings assign, and see what each group role
can reach
Set tenant roles, invite the users your provider does not cover, and audit
who has access