> ## Documentation Index > Fetch the complete documentation index at: https://ona.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Single sign-on (SSO) > Overview of SSO options for Ona Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more. Organization login and security settings showing login methods, SSO providers, and verified domains Single Sign-On (SSO) lets your team log in to Ona using an external Identity Provider (IdP) through OpenID Connect (OIDC). Organization Admins configure login providers, verify email domains, and associate domains with providers. **Key capabilities:** * **Multiple email domains per login provider**: Configure several email domains for a single identity provider, for organizations with multiple subsidiaries or acquired companies. * **Multiple login providers per organization**: Set up more than one identity provider (e.g., both Okta and Azure AD) to accommodate different teams or authentication requirements. * **Cross-organization domain support**: Use the same email domain across different organizations. Users are presented with a list of login options to select their organization. ## Prerequisites * **Admin-level access** to your organization settings. * **Domain/DNS admin privileges** to add a DNS TXT record. Ona uses this record to verify ownership of the domain associated with your organization. * **An Identity Provider** (e.g., Google, GitLab, Okta, Microsoft Entra ID) that supports OpenID Connect (OIDC). You need to create an OIDC application with your IdP and obtain the **Client ID**, **Client Secret**, and **Issuer URL**. ## Setting up Single Sign-On Navigate to **Settings > Login & Identity > Login Configuration**. SSO setup involves three components that can be configured in any order: 1. **Login providers** - Configure connections to your Identity Providers 2. **Domains** - Verify ownership of your email domains 3. **Domain associations** - Link verified domains to login providers ### Step 1. Create a login provider Click **New SSO** to configure how Ona connects with your Identity Provider. Enter a **display name** for your login provider. This name appears on the login provider card in your settings and on the login selection screen when users sign in. Provider-specific setup guides: * [Okta](/ona/sso/okta) * [Google](/ona/sso/google) * [GitLab](/ona/sso/gitlab) * [Entra ID](/ona/sso/entra) * [Amazon Cognito](/ona/sso/cognito) * [PingFederate](/ona/sso/pingfederate) After following the guide for your provider, complete the form with: * **Client ID**: The identifier for your OIDC application. * **Client Secret**: Secret key for authenticating with the IdP. * **Issuer URL**: Endpoint of the OIDC server. Copy the **Callback URL** from the bottom of this form and paste it into the settings of the OIDC application with the IdP. #### Testing your configuration Test the OIDC application by clicking **Test & Continue**. The authentication flow with your Identity Provider opens in a new browser window. Verify the authentication flow works before inviting your team to use SSO login. ### Step 2. Add and verify domains Domains must be verified before they can be used for SSO login. Verification proves ownership of the email domain. Click **New Domain** to add a new domain. #### Verify your domain Add a **TXT record** to your domain's DNS settings. Copy the name and value for the TXT record from the verification view. #### Check the status of your domain After adding the TXT record, click **Verify** to check the status. DNS propagation may take some time. Once the DNS record has propagated, click **Verify** again to update the status. Your email domain must be verified before the [Sign in with SSO option](#log-in-with-single-sign-on) appears on the login screen. ### Step 3. Associate domains with login providers Once you have both a login provider and verified domains, associate the domains with the provider. This tells Ona which identity provider should authenticate users from each email domain. Click on your login provider and select from the dropdown to add a domain. A single domain can be associated with multiple login providers within the same organization. This is useful when different teams using the same email domain need to authenticate through different identity providers. ### Multiple domains and providers You can configure multiple verified domains and multiple login providers to support complex organizational structures. **Common use cases:** * **Subsidiaries and acquisitions**: Configure domains for each company (e.g., `acme.com`, `acme.co.uk`, `acquired-company.com`) under a single login provider. * **Different authentication requirements**: Set up separate providers for employees (Okta) and contractors (Azure AD). * **Regional teams**: Use different identity providers for teams in different regions. ## Log in with Single Sign-on ### Use your email address After setting up SSO, log out and return to the login page. 1. Click **Continue with SSO**. 2. Enter your email address and click **Continue**. The domain of your email address **must match** one of the verified domains associated with a login provider. ### Selecting your organization or provider If your email domain is configured in multiple organizations, or if multiple login providers are associated with the same email domain within your organization, a selection screen appears. Choose the appropriate option to proceed with authentication through your selected identity provider. ### Use the invite link 1. Go to **Settings > Members > Invite members** and copy the invite link for your domain. 2. When you open the invite link while not logged in, only the active login providers are shown. ## Managing Single Sign-on Access Only **Organization Admins** can configure, modify, or disable SSO settings. ### Deactivating login providers A deactivated login provider cannot be used to join your organization. Existing login sessions are not affected. To deactivate a login provider: 1. Go to **Settings > Login and Security**. 2. Click the toggle switch next to the login provider and confirm the action. The last remaining login provider cannot be deactivated. This prevents you from losing access to your organization. ## Advanced configuration ### Additional scopes By default, Ona requests the standard OIDC scopes (`openid`, `email`, `profile`) when authenticating with your Identity Provider. These scopes provide basic user information such as email address, name, and email verification status. If you need additional claims from your IdP (such as group memberships, roles, or department information), configure **additional scopes** on your login provider. These extra scopes tell the IdP to include the corresponding claims in the ID token returned during sign-in. To configure additional scopes: 1. Go to **Settings > Login and Security** and click on your login provider. 2. In the **Additional scopes** field, enter a comma-separated list of scopes (e.g., `groups, roles`). 3. Save and test the configuration with **Test & Continue**. Which scopes are available depends on your Identity Provider. Common examples: * **Okta**: `groups` includes the user's group memberships. * **Microsoft Entra ID**: Configure optional claims in your app registration under **Token configuration**. * **PingFederate**: `groups` or custom scopes defined in your PingFederate configuration. The IdP decides which claims to include based on the scopes requested and its own configuration. Consult your IdP's documentation for the available scopes and the claims they return. ### Claims expression (CEL) A **claims expression** is an optional [CEL (Common Expression Language)](https://github.com/google/cel-spec/blob/master/doc/langdef.md) expression evaluated against the OIDC token claims on every login. When configured, the expression must evaluate to `true` for the login to succeed. If it evaluates to `false` or fails, the user is redirected to the login page with an error message. The expression has access to a `claims` variable containing all claims from the ID token as a map. This includes standard claims (`email`, `email_verified`, `name`, `sub`) and any additional claims made available through [additional scopes](#additional-scopes). To configure a claims expression: 1. Go to **Settings > Login and Security** and click on your login provider. 2. Enter your expression in the **Claims expression** field. 3. Save and test with **Test & Continue** to verify the expression works as expected. #### Examples Require a verified email address: ```cel theme={null} claims.email_verified == true ``` Restrict login to a specific email domain: ```cel theme={null} claims.email.endsWith("@example.com") ``` Restrict login to members of a specific group: ```cel theme={null} "engineering" in claims.groups ``` Combine multiple conditions: ```cel theme={null} claims.email_verified && "staff" in claims.groups ``` #### Example: restricting login to a specific group A common use case is limiting access to users who belong to a particular group in your Identity Provider. This requires both additional scopes and a claims expression: 1. **Configure the scope**: Edit your login provider and add `groups` to the **Additional scopes** field. This tells the IdP to include group membership claims in the token. 2. **Set the claims expression**: Enter an expression like `"engineering" in claims.groups` in the **Claims expression** field. 3. **Test the configuration**: Click **Test & Continue**. If your account is a member of the `engineering` group, the test succeeds. Otherwise, you see a denial message. When a user who is not in the required group attempts to log in, they are redirected to the login page with the message: *"Login denied: your account does not meet the required claims conditions."* Claims expressions have a maximum length of 4096 characters. The expression must evaluate to a boolean value. Non-boolean results are rejected. ## Problems and solutions 1. Error: *The redirect URI included is not valid.* Make sure the redirect URI in the OIDC application with your Identity Provider matches the Callback URL shown in Ona, e.g., `https://app.gitpod.io/auth/oidc/callback`. 2. Error: *no such host* Make sure the **Issuer URL** is correct, e.g., `https://dev-16686455.okta.com`. You can verify the URL by appending `/.well-known/openid-configuration` and opening it in your browser, e.g., `https://dev-16686455.okta.com/.well-known/openid-configuration`.