Configure Single Sign-On

Enterprise requires OpenID Connect (OIDC) for authentication, for example with Identity Providers (IdP) such as Google, Okta, Azure AD and AWS Cognito.

General instructions

  • You will need to create a configuration with your Identity Provider and provide the “redirect URI” you can copy from this screen.

  • Once you’ve created your Identity Provider configuration, you should copy and paste the Issuer URL, Client ID and Client Secret values on this screen.

  • Clicking “Verify SSO Configuration” will ensure that validity of the values by authenticating your account. If successful, your user will be created and configured with the “owner” role. Subsequent users that log in will be granted the default “member” role.

    Configure Single Sign-on

Identity Provider specific instructions

Let us go through a detailed walk through of how to setup of how to setup SSO in various identity providers:


Okta

As prerequisites, you will need the following:

Creating a Gitpod SSO Integration

  1. On the Okta Admin dashboard, navigate to Applications

  2. Select Create App Integration

    Applications - Okta Dashboard

  3. Select the following options and click Next

    • Sign-in method: OIDC - Open ID Connect
    • Application type: Web Application

    Create App Integration - Okta Dashboard

  4. Specify General Settings

    • App integration name: Gitpod (or choose your own name)
    • Sign-in redirect URIs: copy this value from your Gitpod setup screen (see details above under “General instructions”)
    • Sign-out redirect URIs: none
    • Trusted Origins: none
    • Assignments: choose option appropriate to your organization

    Specify Okta settings - Okta Dashboard

  5. Obtain Client ID & Client Secret

    • Copy the Client ID and use it as input in Gitpod setup (see details above under “General instructions”)
    • Copy Client Secret and use it as input in Gitpod setup (see details above under “General instructions”)
    • Set the Issuer to your Okta instance, eg: https://amazingco.okta.com/

    Configure Client Secrets - Okta Dashboard

  6. Continue with Gitpod SSO Configuration verification: Clicking “Verify SSO Configuration”


Google

As prerequisites you will need the following:

Creating a Gitpod SSO Integration

  1. Navigate to your Google Cloud Console, API Credentials

  2. Select Create Credentials, and choose OAuth client ID

    Create credentials - Google Cloud Dashboard

  3. Configure your OAuth Client ID, by specifying the Authorized Redirect URIs: Once you’ve created your Identity Provider configuration, you should copy…

  4. Obtain the Client ID & Client Secret and input these into your Gitpod Setup page

    OAuth Client Created - Google Cloud Dashboard

  5. Set Provider’s Issuer URL to https://accounts.google.com

  6. Proceed to verify the integration on the Gitpod setup page: Clicking “Verify SSO Configuration”


Azure AD

As prerequisites you will need the following:

  • Access to Azure Directory, to Register an Application

Creating a Gitpod SSO Integration

  1. Navigate to your Azure portal > App Registrations

  2. Select New Registration

    New registration - Azure AD Dashboard

  3. Name your application - e.g. Gitpod

  4. Select supported account types depending on your organizational needs. Most likely you want Accounts in this organizational directory only

  5. Copy the redirect URL from the Gitpod SSO setup page and set it as the Redirect URI, selecting Web as the application type

    Register Application - Azure AD Dashboard

  6. From the App Registration Overview, you should obtain the Application (client) ID and copy it into your Gitpod SSO setup page

  7. Create a client secret - navigate to Certificates & Secrets, click New client secret

    Create client secret - Azure AD Dashboard

  8. Name the secret, and set expiry according to your needs.

    📌 Once the client secret expires, you (nor anyone else in your organization) will be able to log in to Gitpod. You will need to update the SSO configuration (secret) to continue using SSO.

  9. Obtain the Secret Value and copy into into the Gitpod SSO Client Secret input field

  10. Grant the application access to OpenId email , openidand profile information

    • Navigate to API Permissions
    • Select Microsoft Graph
    • Enable OpenId.email, OpenId.openid and Openid.profile Request API Permissions - Azure AD Dashboard
    • Once saved, your configured permissions should look as follows: Configure API Permissions - Azure AD Dashboard
  11. Obtain the Provider URL

    • Navigate to your App Registration > Overview
    • Click endpoints Endpoints - Azure AD Dashboard
    • Find the entry for OpenID Connect metadata document
    • Use the URL before the .well-known/openid-configuration segment,
      • For example: https://login.microsoftonline.com/512571ea-9fc5-494e-a300-625b33c8efa6/v2.0/
  12. Proceed to Verify the SSO configuration on the Github SSO setup page: : Clicking “Verify SSO Configuration”


AWS Cognito

Choose this option if you already use AWS Cognito. AWS Cognito is also a good option in a testing or Proof of Value (PoV) scenario where you don’t have an IDP you can easily integrate with. In this scenario, most settings should be left at their defaults.

Follow the Cognito User Pool setup process, then copy the necessary values into the Gitpod SSO Configuration UI

  1. Navigate to the Cognito page in the AWS console. Select create user pool: Congiton User Pool Process
  2. Configure sign-in experience: Congito Sing In Requirements
  • Select Cognito user pool as provider type
  • Select email as the Cognito user pool signin option
  1. Configure Security requirements: Congito Security Requirements
    • For development purposes, consider modifying the MFA enforcment policy to not require MFA. For all production use cases, configure the MFA and user account recovery sections according to organizational guidelines
  2. Configure sign-up experience: Congito Security Requirements
    • Disable Self Registration if you want to limit access. For example, if your instance is accessible on the public internet, you may not want anyone to be able to self-register. ::WARN> In the Required Attributes section, ensure that name is selected:

      Required Attribute Name

  3. Configure Message Delivery: Configure message delivery
    • For dev Setups, use Cognito as the email provider; for production setups, use company SES setup
  4. Integrate your app: Integrate your app
    • Follow company best practice for most settings
    • Ensure to select Generate a client secret in the Client secret section: Required client secret
    • Define the call back url as provided by the Enterprise instance in the Configure single sign-on setup page (see above): Required callback url
    • As the identity provider, select Cognito (under Advanced app client settings)
    • OAuth 2.0 grant types, select Auth Code Grant
    • Under OpenID Connect Scopes, select OpenID, Email, Profile: Required callback url
  5. Now create the cognito user pool. The review page should look similar to this:
  6. Start pasting the necessary values into the Gitpod SSO setup page. Navigate to:
language icon text
https://cognito-idp.<insert_region>.amazonaws.com/<insert_user_pool_id>/.well-known/openid-configuration

This will return a web page with raw json data: Issuer URL

  • Copy the issuer URL highlighted above into the respective field on the Gitpod SSO setup page
  1. Navigate to the Cognito console, and find the User pool created above. Navigate to the App client meta data as below: App Client Data
  • Copy the Client ID from the Cognito app client page into the respective field on the Gitpod SSO setup page
  • Copy the Client Secret into the respective field on the Gitpod SSO setup page
  1. Proceed to Verify the SSO configuration on the Github SSO setup page by clicking “Verify SSO Configuration”

Was this helpful?