Skip to main content
This feature is only available on the Enterprise tier. Contact sales to learn more about upgrading.
This section helps you, as an Organization Admin, set up and manage Single Sign-On (SSO) for your team. You’ll learn how to enable SSO, control access, and troubleshoot common issues to keep your team logging in smoothly and securely.

​
Overview

Single Sign-On (SSO) lets your team log in to your organization using their existing session with an external Identity Provider (IdP), such as Okta or Azure AD, through OpenID Connect (OIDC). This simplifies user authentication, enhances security, and streamlines access management across your organization. Key capabilities:
  • Multiple email domains per login provider: Configure several email domains for a single identity provider, ideal 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

This is what you will need to have in order to enable SSO:
  • Admin-level access to your organization settings.
  • Domain/DNS admin privileges so you can add a DNS TXT record. This TXT record is used by Ona to verify ownership of the domain associated with your organization.
  • Access to an Identity Provider (e.g. Google, Gitlab, Okta, Microsoft Entra ID) that supports OpenID Connect (OIDC).
    • You’ll need to create an OIDC application with your Identity Provider and obtain the Client ID, Client Secret, and Issuer URL.

​
Setting up Single Sign-On

To begin setting up Single Sign-On, navigate to Organization Settings and choose Login and security from the left-hand menu. SSO not set up Log in and security - Initial state SSO setup involves three main 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 on New SSO to configure how Ona will connect with your Identity Provider. Enter a display name for your login provider. This name will appear on the login provider card in your settings and on the login selection screen when users sign in. Configure login provider Configure login provider We’ve created detailed guides for the most popular providers to help you set up the connection: After following the guide for your provider, you’ll need three important pieces of information to complete the form:
  • 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

Before rolling this out to your team, let’s make sure everything is working properly: Test the OIDC application by clicking Test & Continue
  • The authentication flow with your Identity Provider should open in a new browser window.
  • Please verify the authentication flow works for you before inviting your team to use the SSO login.
Provider configured Login provider configured

​
Step 2. Add and verify domains

Domains must be verified before they can be used for SSO login. This verification proves ownership of the email domain. Click on New Domain to add a new domain. Add login domain Add login domain

​
Verify your domain

To verify your domain, you’ll need to add a TXT record to your domain’s DNS settings. Copy the name and value for the TXT record from the verification view. Domain TXT record Domain TXT record details

​
Check the status of your domain

After adding the TXT record, click Verify to check the status of your domain verification. A delay in DNS updates is expected, so no worries! Domain not verified Domain pending verification Once the DNS record has propagated, click the verify button again to update the status. Domain verified Domain verified
Please note that your email domain must be verified before the Sign in with SSO option can be used on the Login screen.

​
Step 3. Associate domains with login providers

Once you have both a login provider and verified domains, you need to 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. Add domain to provider Associate domain with login provider Note: 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. Multiple domains verified Multiple verified domains Multiple providers Multiple login providers configured 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

Once you’ve finished setting up SSO for your organization, you’ll need to log out before heading back to the Login page.
  • Click the Continue with SSO button to sign in using your new SSO setup.
  • 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.
Login with email Enter email address

​
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, you’ll be presented with a selection screen. Login selection Select organization or login provider Choose the appropriate option to proceed with authentication through your selected identity provider.
  • Go to Settings > Members > Invite members and copy the invite link for your domain.
  • When you open the invite link while not logged in, you will only see the active login providers.

​
Managing Single Sign-on Access

Only Organization Admins are allowed to configure, modify, or disable SSO settings. Regular members will not have access to these options.

​
Deactivating login providers

A deactivated login provider cannot be used to join your organization. The existing login sessions are not affected by this setting. If you need to deactivate a login provider:
  • Go to Settings > Log In and Security.
  • Click the toggle switch next to the login provider and confirm the action.
Provider disabled Login provider disabled
To protect you from losing access to your organization, the one remaining login provider cannot be deactivated.

​
Problems and solutions

While setting up SSO, some issues may arise due to misconfigurations or external factors. These can include problems with your Identity Provider settings, incorrect credentials, or network issues. To help you navigate these challenges, we’ve included an FAQ section below with solutions to common problems.
  1. Error: The redirect URI included is not valid.
    • Make sure to paste the correct redirect URI into the OIDC application with your Identity Provider, e.g. https://app.gitpod.io/auth/oidc/callback.
  2. Error: no such host
    • Make sure to paste the correct Issuer URL, e.g. https://dev-16686455.okta.com. You can also verify the URL by appending the OIDC Discovery path /.well-known/openid-configuration and open the resulting URL in your browser, e.g. https://dev-16686455.okta.com/.well-known/openid-configuration