Single Sign-on

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.

Setup Single Sign-on for the organization

Prerequisites

This is what you will need to have in order to enable SSO:

• Admin-level access to your organization settings.

• 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.

Step-by-step guide to set up SSO

1. Navigate to Organization Settings

• Select Settings > Log in and security from the left-hand menu.

  

2. Setup

• Click the Setup button to start configuring the SSO.

• Enter the Email domain. The domain will be used to identify your organization when your team mates select Sign in with SSO on the Login screen.

• Now you need to setup the OIDC application with your Identity Provider. You’ll find specific steps for some of the most popular providers here:

  • Okta
  • Google

• Fill out the form with the following details you should be able to obtain in the previous step:

  • 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.

  

3. Save and test the configuration

• Test the SSO configuration by clicking Test & Continue

• The authentication flow with your Identity Provider should open in a new browser window.

• Please ensure a successfull authentication before inviting your team to use the SSO login.

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: only email domains of existing members can be used as domains

   • Currently, the only way to verify the domain of your organization is by using it with your default login provider, e.g. Google, or GitHub.

     

2. 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.

     

3. 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 you browser, e.g. https://dev-16686455.okta.com/.well-known/openid-configuration

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.

  

• Now enter your email address and click Continue. The domain of your email address must match the domain of your SSO configuration.

  

Use the invite link

• 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 can not 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.

To protect you from losing access to your organization, the one remaining login provider cannot be deactivated.