> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS (V2)

> Access AWS resources from environments using OIDC V2 tokens.

<Note>This guide covers **V2 OIDC tokens**. For new integrations, see the [AWS OIDC V3 guide](/ona/identity/aws-oidc), which uses the current token format with flat claims and customizable sub fields. V2 tokens remain fully supported.</Note>

Ona environments can retrieve AWS credentials using [OpenID Connect (OIDC)](/ona/configuration/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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) in AWS to establish trust with Ona:

* **Provider URL**: `https://app.gitpod.io`
* **Audience**: `sts.amazonaws.com`

<Note>View the OIDC configuration at `https://app.gitpod.io/.well-known/openid-configuration`</Note>

See [Identity providers and federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html) in AWS docs.

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

[Create an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html) that Ona environments can assume. Use JWT claims to restrict which environments can assume the role.

<Note>Follow the principle of least privilege - only allow relevant environments and users to assume your role.</Note>

```json theme={null}
{
	"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
		}
	]
}
```

<Note>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.</Note>

Define condition keys using the OIDC provider name (`app.gitpod.io`) plus the claim (`:aud`, `:sub`, etc.):

**Allow all environments in an organization:**

```json theme={null}
{
	"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:**

```json theme={null}
{
	"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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#condition-keys-wif) and [string condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String) in AWS docs.

## Step 3: Assume the role

<Note>Requires AWS CLI installed in your environment.</Note>

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](/ona/configuration/tasks-and-services/overview) for automatic authentication on startup:

```bash theme={null}
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`](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role-with-web-identity.html) in AWS docs.

## FAQ

<Accordion title="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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) you receive can access EC2, EKS, S3, RDS, and more.
</Accordion>

<Accordion title="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.
</Accordion>

## Troubleshooting

<Accordion title="Verifying the JWT claims against the trust policy">
  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.
</Accordion>