Configure Single Sign-On

As prerequisites, you will need the following:

• Access to your Okta instance
• Permission to create an app integration

Creating a Gitpod SSO Integration

1. On the Okta Admin dashboard, navigate to Applications

2. Select Create App Integration

   

3. Select the following options and click Next

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

   

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

   

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/

   

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

As prerequisites you will need the following:

• Access to setup a new API Credentials in your GCP Account

Creating a Gitpod SSO Integration

1. Navigate to your Google Cloud Console, API Credentials

2. Select Create Credentials, and choose OAuth client ID

   

3. Configure your OAuth Client ID, by specifying the Authorized Redirect URIs. You will be able to find it on the setup page.

   

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

   

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”

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

   

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

   

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

   

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
    • Once saved, your configured permissions should look as follows:

11. Obtain the Provider URL

    • Navigate to your App Registration > Overview
    • Click endpoints
    • 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”

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:
2. Configure sign-in experience:

• Select Cognito user pool as provider type
• Select email as the Cognito user pool signin option

3. Configure 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
4. Configure sign-up experience:
   • 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:

     

5. Configure Message Delivery:
   • For dev Setups, use Cognito as the email provider; for production setups, use company SES setup
6. Integrate your app:
   • Follow company best practice for most settings
   • Ensure to select Generate a client secret in the Client secret section:
   • Define the call back url as provided by the Enterprise instance in the Configure single sign-on setup page (see above):
   • 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:
7. Now create the cognito user pool. The review page should look similar to this:
8. Start pasting the necessary values into the Gitpod SSO setup page. Navigate to:

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:

• Copy the issuer URL highlighted above into the respective field on the Gitpod SSO setup page

9. Navigate to the Cognito console, and find the User pool created above. Navigate to the App client meta data as below:

• 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

10. Proceed to Verify the SSO configuration on the Github SSO setup page by clicking “Verify SSO Configuration”

As prerequisites you will need the following:

• Admin Permission of your Self-hosted GitLab

Creating a Gitpod SSO Integration

1. Navigate to your GitLab instance’s applications settings page. eg: https://gitlab-demo.gitpod.io/admin/applications.

2. Click on the New application button.

   

3. Specify General Settings and Save application.

   • Name: Gitpod
   • Redirect URI: copy this value from your Gitpod setup screen (see details above under “General instructions”)
   • Confidential: Yes
   • Expire access tokens: Yes
   • Scopes: select read_user, openid, profile and email

   

4. Obtain Client ID & Client Secret

   • Copy the Application ID and use it as input in Gitpod setup (see details above under “General instructions”)
   • Copy Secret and use it as input in Gitpod setup (see details above under “General instructions”)
   • Set the Issuer to your Okta instance, eg: https://gitlab-demo.gitpod.io

   

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

Creating a Gitpod SSO Integration

1. Navigate to your SaaS GitLab group’s applications settings page. eg: https://gitlab.com/groups/<group_name>/-/settings/applications.

2. Click on the Add new application button.

   

3. Specify General Settings and Save application.

   • Name: Gitpod
   • Redirect URI: copy this value from your Gitpod setup screen (see details above under “General instructions”)
   • Confidential: Yes
   • Expire access tokens: Yes
   • Scopes: select read_user, openid, profile and email

   

   

4. Obtain Client ID & Client Secret

   • Copy the Application ID and use it as input in Gitpod setup (see details above under “General instructions”)
   • Copy Secret and use it as input in Gitpod setup (see details above under “General instructions”)
   • Set the Issuer to your Okta instance, eg: https://gitlab-demo.gitpod.io

   

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

6. Restrict with CEL expression. More available keys see OIDC document on GitLab

   Security note: To avoid everyone has a GitLab account to sign up in your Gitpod installation, you must restrict claims with CEL expression (syntax of CEL)

• Limit users to people who is a direct member of group, example group name gitpod-team
  'gitpod-team' in claims.groups_direct

• Limit users to people who is a direct member of multiple groups, example group name gitpod-team and gitpod-team-2/sub_group
  'gitpod-team' in claims.groups_direct && 'gitpod-team-2/sub_group' in claims.groups_direct

• Limit users by email ends with @gitpod.io
  claims.email_verified && claims.email.endsWith('@gitpod.io')