Single Sign-on with Microsoft Entra ID

You can set up Single Sign-on (SSO) with Microsoft Entra ID for your team.

This section helps you to create an OIDC application with Microsoft Entra ID. The Client ID, Client Secret, and Issuer URL of this OIDC application are required to setup SSO in Gitpod. See the Step-by-step guide for the general instructions.

Prerequisites

As prerequisites you will need the following:

• Access to Microsoft Entra admin center

Create an OIDC application

1. On the Microsoft Entra admin center, navigate to Identity > Applications

2. Select New Registration

   

3. Specify General Settings

   • App name, e.g. Gitpod

   • Platform: Web

   • Redirect URI: https://app.gitpod.io/auth/oidc/callback

   • 

4. Obtain Client Secret from the Certificates & secrets page

   • Once the application is registered, navigate to the subpage Certificates & secrets to create and obtain a new client secret.

     • Click the New client secret button

     • Adjust the expiry of the client secret

     • Then copy the value of the client secret to be pasted in Gitpod’s SSO setup

5. Configure OIDC Scopes

   • The default selection of OIDC scopes in Microsoft Entra ID doesn’t meet the requirements for Gitpod. Please navigate to API permissions > Add a permission to make the necessary changes.

     

     • Selec Delegated permissions and OpenId, then ensure to enable the following scopes:

       • email

       • openid

       • profile

       • 

6. Obtain Issuer URL from Endpoints tab

   • Navigate to the Overview page and select Endpoints

     

   • Copy to the Authority URL page to be used as Issuer URL in Gitpod’s SSO setup

     

     Note: Validate the Issuer URL by checking the OIDC Discovery location. In some configurations, the Issuer URL needs to be adjusted.

     • If the Authority URL reads like https://login.microsoftonline.com/{tenant}/v2.0, the OIDC Discovery location is https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration. Open this URL in your browser and check the issuer field.

     • Check the issuer field in the OIDC Discovery output and ensure this matches the Authority URL (Issuer URL). If not, e.g. if it reads like https://sts.windows.net/{tenant}, please try again with{authority_url}/v2.0/.well-known/openid-configuration and use {authority_url}/v2.0 as Issuer URL in Gitpod’s SSO setup.

7. Obtain the Client ID from the Overview page

   • Navigate to the Overview page and copy the Application (client) ID value to be used as Client ID in Gitpod’s SSO setup

     

8. Continue with the SSO configuration in Gitpod: Clicking Save & Test