Gitpod is a flexible tool that works with many cloud providers, including AWS. This guide describes how to integrate Gitpod and AWS using OpenID Connect (OIDC).

​
OIDC Integration with AWS

Gitpod can connect environments to AWS using Gitpod support for OpenID Connect, which allows environments to retrieve AWS access credentials without using static credentials or environment variables.

In this authentication flow, an IAM role is created in an external AWS account, accessible through the gitpod command in Gitpod. The generated JWT token includes claims about the environment and its owner, and is exchanged with AWS for an STS token. That STS token is associated with an IAM role and inherits any access granted to that role. Access control configuration is the responsibility of the AWS account owner/administrator.

​
Step 1: Create an “AWS Identity Provider” resource

To connect Gitpod to AWS, you need to create an “IAM identity provider” to establish a trust relationship between your AWS account and Gitpod. Gitpod supports OpenID Connect (OIDC), so follow AWS’s guide here to create an OIDC identity provider.

  • Configure the URL of the identity provider to: https://app.gitpod.io
  • The client ID / Audience should be set to: sts.amazonaws.com

Add /.well-known/openid-configuration to the end of the identity provider’s URL to see the provider’s publicly available configuration document and metadata: https://app.gitpod.io/.well-known/openid-configuration

Read more:

​
Step 2: Create an AWS role with a trust policy

Now that your AWS account is set up to trust Gitpod, you need to create an AWS IAM role that can be assumed by the Gitpod environment user. You can restrict who has access to the assumed role based on claims in your Gitpod environment JWT token.

We strongly recommend you adhere to the principle of least privilege, and ensure that only relevant environments and users can assume your AWS role.

{
	"Claims": {
		"aud": "sts.amazonaws.com",
		"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
		}
	]
}

You can inspect the claims that will be sent to AWS by running gitpod idp token --decode --audience sts.amazonaws.com inside a Gitpod environment. Pay attention to the sub claim containing the organization, project, and environment information.

To adjust the IAM role trust policy to restrict which environments can assume the role, you can define condition keys using the name of the OIDC provider (created in step 1, e.g. app.gitpod.io) followed by the claim (:aud, :sub, etc.). The examples below show how this works. Read more about these OIDC condition keys here.

Here are some examples restricting who can assume the role depending on the sub key contents:

This example shows that only environments created within a specific organization can assume this role:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"Federated": "arn:aws:iam::981341800645:oidc-provider/app.gitpod.io"
			},
			"Action": "sts:AssumeRoleWithWebIdentity",
			"Condition": {
				"StringEquals": {
					"app.gitpod.io:aud": "sts.amazonaws.com"
				},
				"StringLike": {
					"app.gitpod.io:sub": "org:0191e223-1c3c-7607-badf-303c98b52d2f/*"
				}
			}
		}
	]
}

This example shows how to grant access only to environments created from a specific project:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"Federated": "arn:aws:iam::981241700645:oidc-provider/app.gitpod.io"
			},
			"Action": "sts:AssumeRoleWithWebIdentity",
			"Condition": {
				"StringEquals": {
					"app.gitpod.io:aud": "sts.amazonaws.com"
				},
				"StringLike": {
					"app.gitpod.io:sub": "org:0191e223-1c3c-7607-badf-303c98b52d2f/prj:019527e4-75d5-704d-a5a4-a2b52cf56198/*"
				}
			}
		}
	]
}

Read more:

​
Step 3: Assume the AWS role to retrieve the AWS credentials

The following assumes that your environment has the AWS CLI installed so that it can call aws sts assume-role-with-web-identity.

You can either call the AWS CLI assume-role command manually, or use the helper command within the gitpod CLI, gitpod idp login aws which will automatically update your AWS CLI credentials file.

The token expiry can be customized using --duration-seconds=<token-expiry-in-seconds>, this configuration option exactly matches the --duration-seconds configuration option offered by AWS CLI. The default is 3600 seconds. Note, to use a longer expiry your AWS Administrator must allow for longer sessions.

You can can run the following to assume the role and retrieve secrets from AWS Secrets Manager, or you can extend your Automation to authenticate with AWS automatically on startup.

gitpod idp login aws --role-arn <your-iam-role-arn> [--duration-seconds=<expiry-in-seconds>]
aws secretsmanager get-secret-value --secret-id database_connection_string --region us-east-1 | jq .SecretString

Read more:

​
Troubleshooting

Use gitpod idp token --decode --audience sts.amazonaws.com to print your environment JWT token. Ensure that any claims against the sub match the trust policy in AWS.

​
Frequently asked questions

​
What AWS resources can I access with OIDC in Gitpod?

When you use OIDC in Gitpod, you get an AWS access token called an STS token. This STS token lets you access various AWS resources, like EC2 instances, EKS clusters, S3 Buckets, RDS databases, and more. In simple terms, if you’re trying to do something that you can do with AWS CLI or SDK, it will work in Gitpod, provided you set up the required access through your IAM role.

​
How fine-grained is the AWS access control in Gitpod?

When you connect to AWS through OIDC in Gitpod, you get an STS token that represents an AWS IAM role. This IAM role has specific policies or rules that define what can and can’t be accessed in AWS. The level of access you have in Gitpod to AWS resources depends on the policies you attach to the assumed IAM role.