OpenID Connect (OIDC)

You can use OIDC authentication to connect Gitpod environments to cloud providers or third parties such as AWS, Azure, GCP, or secret management services like Vault. OIDC integration eliminates the need to manually distribute access credentials, secrets, and other key material via environment variables or other methods.

​

What is OIDC?

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol, which allows clients to verify identity.

OIDC leverages a JWT (JSON Web Token) that contains claims about the caller. Claims are statements that can include information such as name, email address, or repository metadata.

OIDC provides a reliable way to establish a user’s identity, including authentication and basic profile information. It gives third-party applications a standardized, secure, and scalable method to authenticate and authorize users. When used with Gitpod, it helps automate secure access to third-party services that your environments might need to interact with.

​

Setting up OIDC Authentication with a third party

Setting up OIDC Authentication generally involves three main steps:

1. Establish Trust: Register Gitpod with your OIDC-supported third party (like AWS, Google, etc.). This third party becomes the audience in your JWT token generated in Gitpod.

2. Setup Trust Rules: Configure what the JWT claims must contain to be exchanged for a valid auth token. Here you can implement fine-grained access controls.

3. Exchange the JWT token: Once trust and trust rules are established, use the JWT tokens generated by the gitpod idp token command to authenticate with the third party.

​

Provider specific guides

• AWS

Read more:

• [Auth0 docs] OpenID Connect Protocol

​

Gitpod CLI integration

You can retrieve a JWT token for OIDC using gitpod idp. To retrieve the OIDC token for the current environment, run gitpod idp token.

For example, to request a new OIDC JWT for example.org, execute:

$ gitpod idp token --audience example.org
eyJhbGciOiJSUzI1NiIsImtpZCI6ImlkLTE2ODQ3NTc4MDY...

To decode the output, use the --decode flag:

$ gitpod idp token --audience example.org --decode

Once decoded, the result will resemble this JSON object:

{
	"Claims": {
		"aud": "example.org",
		"exp": 1740517845,
		"iat": 1740514245,
		"iss": "https://app.gitpod.io",
		"org": "0191e223-1c3c-7607-badf-303c98b52d2f",
		"sub": "org:0191e223-1c3c-7607-badf-303c98b52d2f/prj:019527e4-75d5-704d-a5a4-a2b52cf56198/env:019527e4-75d5-704d-a5a4-a2b52cf56196"
	},
	"Header": [
		{
			"KeyID": "k0",
			"JSONWebKey": null,
			"Algorithm": "RS256",
			"Nonce": "",
			"ExtraHeaders": null
		}
	]
}

​

Access Control Examples

​

Granting access to anyone in the organization

Depending on the Principal using the system, the sub claim will have the following format:

• Users: sub: "org:<orgID>/user:<userID>"
• Runners: sub: "org:<orgID>/rnr:<runnerID>"
• Environments without a Project: sub: "org:<orgID>/env:<environmentID>"
• Environments from a Project: sub: "org:<orgID>/prj:<projectID>/env:<environmentID>"

​

Granting access to anyone in the organization

You can configure your third-party service to grant access based on the org:<orgID> prefix.

​

Granting access to an Environment created from a specific project

You can grant your third-party service access to an environment created from a specific project by matching the org:<orgID>/prj:<projectID> prefix.

​

Grant access to a specific Environment

You can grant your third-party service access to a specific environment by matching the org:<orgID>/prj:<projectID>/env:<environmentID> prefix.