Skip to main content
This guide covers V2 OIDC tokens. For new integrations, see the AWS OIDC V3 guide, which uses the current token format with flat claims and customizable sub fields. V2 tokens remain fully supported.
Ona environments can retrieve AWS credentials using OpenID Connect (OIDC) - no static credentials needed. The ona CLI generates a JWT token with claims about the environment and owner, which AWS exchanges for an STS token associated with an IAM role you configure.

​
Step 1: Create an AWS identity provider

Create an OIDC identity provider in AWS to establish trust with Ona:
  • Provider URL: https://app.gitpod.io
  • Audience: sts.amazonaws.com
View the OIDC configuration at https://app.gitpod.io/.well-known/openid-configuration
See Identity providers and federation in AWS docs.

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

Create an IAM role that Ona environments can assume. Use JWT claims to restrict which environments can assume the role.
Follow the principle of least privilege - only allow relevant environments and users to assume your 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
		}
	]
}
Inspect claims by running ona idp token --decode --audience sts.amazonaws.com in an environment. Note the sub claim contains organization, project, and environment IDs.
Define condition keys using the OIDC provider name (app.gitpod.io) plus the claim (:aud, :sub, etc.): Allow all environments in an organization: 
{
	"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/*"
				}
			}
		}
	]
}
Allow only environments 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/*"
				}
			}
		}
	]
}
See OIDC condition keys and string condition operators in AWS docs.

​
Step 3: Assume the role

Requires AWS CLI installed in your environment.
Use ona idp login aws to assume the role and update your AWS credentials file:
  • --duration-seconds sets token expiry (default: 3600 seconds, longer sessions require AWS admin approval)
You can run this manually or add it to your automations for automatic authentication on startup: 
ona 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
See assume-role-with-web-identity in AWS docs.

​
FAQ

​
What AWS resources can I access?

Any resource accessible via AWS CLI or SDK works in Ona, provided your IAM role has the required permissions. The STS token you receive can access EC2, EKS, S3, RDS, and more.

​
How fine-grained is access control?

Access depends entirely on the policies attached to your assumed IAM role. Configure permissions in AWS IAM as you would for any other OIDC-based access.

​
Troubleshooting

Use ona 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.