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

# AWS

> Federate AWS IAM outbound web identity (or EKS) JWTs into short-lived TrueFoundry access tokens.

AWS workloads can authenticate to TrueFoundry without a static Virtual Account token by exchanging an AWS-signed OIDC JWT. The usual path is [AWS IAM outbound web identity federation](https://aws.amazon.com/blogs/aws/simplify-access-to-external-services-using-aws-iam-outbound-identity-federation/) (`sts:GetWebIdentityToken`). EKS pods can instead use a projected service-account token and the [Kubernetes](https://www.truefoundry.com/docs/platform/identity-providers/workload-identity-federation/kubernetes.md) provider.

TrueFoundry requires a `sub` claim match on the Virtual Account **Claims** (or Agent **Subject**) mapping. For outbound federation tokens, `sub` is typically the IAM role ARN.

For concepts and the shared exchange API, see [Workload Identity Federation](https://www.truefoundry.com/docs/platform/identity-providers/workload-identity-federation/overview.md).

## Prerequisites

* An AWS workload (Lambda, EC2, ECS, or EKS) that can call STS with an attached IAM role.
* Outbound web identity federation enabled on the AWS account (required for `GetWebIdentityToken`).
* A [Virtual Account](https://www.truefoundry.com/docs/platform/virtual-account-management.md) or Agent with the permissions the workload needs.

## Configure AWS (outbound web identity)

### Enable outbound federation

In the AWS console: **IAM → Account settings → Outbound web identity federation**. Or:

```bash theme={"dark"}
aws iam enable-outbound-web-identity-federation
```

### Allow the role to mint tokens

```json theme={"dark"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sts:GetWebIdentityToken"],
      "Resource": "*"
    }
  ]
}
```

### Issuer URL for your account

After outbound federation is enabled, IAM shows a token issuer URL of the form:

`https://<uuid>.tokens.sts.global.api.aws`

Copy that value for the TrueFoundry **Issuer URL**. Confirm the JWKS URL from the issuer's OIDC discovery document (`/.well-known/openid-configuration` → `jwks_uri`).

### Mint a token in the workload

Request a token with the audience you will register on TrueFoundry (for example `truefoundry`):

```bash theme={"dark"}
aws sts get-web-identity-token \
  --audience truefoundry \
  --duration-seconds 300 \
  --signing-algorithm RS256 \
  --region <aws-region> \
  --query WebIdentityToken \
  --output text > /tmp/aws-jwt
```

TrueFoundry verifies workload JWTs with **RS256** only. `GetWebIdentityToken` requires `--signing-algorithm`; use `RS256` (not `ES384`).

`GetWebIdentityToken` is not available on the STS global endpoint (`sts.amazonaws.com`). Current AWS CLI/SDK defaults usually use regional STS when `--region` / `AWS_REGION` is set. If your environment uses legacy STS endpoint mode (`AWS_STS_REGIONAL_ENDPOINTS=legacy`), either set `AWS_STS_REGIONAL_ENDPOINTS=regional` or add `--endpoint-url https://sts.<aws-region>.amazonaws.com`.

Decode the JWT locally and confirm `iss`, `aud`, and `sub` (role ARN) before configuring TrueFoundry.

## Configure TrueFoundry

1. **Settings > Security & Access > Identity Providers** → add provider type **AWS**.
2. Set **Issuer URL** to your account STS issuer, **Allowed Audiences** to the audience used in `GetWebIdentityToken`, and **JWKS URI** from discovery.
3. Map the Virtual Account (or Agent) on `sub`:

**Virtual Account — Claims**

```yaml theme={"dark"}
identity_provider_mapping:
  - identity_provider: aws-outbound-federation
    claims:
      sub: arn:aws:iam::123456789012:role/truefoundry-gateway
```

**Agent — Subject** (YAML key is still `claims`)

```yaml theme={"dark"}
identity:
  type: identity-provider-backed
  identity_provider_mapping:
    - identity_provider: aws-outbound-federation
      claims:
        sub: arn:aws:iam::123456789012:role/truefoundry-gateway
```

Required key for `aws`: `sub`. You may add further claim matches when your token includes them and you want to pin them.

## Exchange and call TrueFoundry

```bash theme={"dark"}
WORKLOAD_JWT=$(cat /tmp/aws-jwt)

curl -sS "https://<tenant-host-origin>/<tenant>/oauth2/v1/token" \
  -H 'Content-Type: application/json' \
  -d "{
    \"grant_type\": \"urn:ietf:params:oauth:grant-type:token-exchange\",
    \"subject_token\": \"$WORKLOAD_JWT\",
    \"subject_token_type\": \"urn:ietf:params:oauth:token-type:jwt\",
    \"tfy_subject\": \"virtual_account:<virtual-account-name>\"
  }"
```

`<tenant-host-origin>` is the issuer origin from OpenID discovery. The exchange path is `/{tenant}/oauth2/v1/token` (no `/api/svc`). Prefer `token_endpoint` from `GET https://<tenant-host-origin>/<tenant>/.well-known/openid-configuration`. For Agents, set `tfy_subject` to `agent:<agent-name>`.

Use the returned `access_token` as `Authorization: Bearer` on the [AI Gateway](https://www.truefoundry.com/docs/ai-gateway/authentication.md) or APIs. Full exchange details: [Workload Identity Federation](https://www.truefoundry.com/docs/platform/identity-providers/workload-identity-federation/overview.md#exchange-the-platform-jwt).

## EKS alternative

If the workload is only an EKS pod and you prefer projected service-account tokens, use the [Kubernetes](https://www.truefoundry.com/docs/platform/identity-providers/workload-identity-federation/kubernetes.md) provider with the cluster OIDC issuer and `kubernetes.io/*` claims instead of this AWS STS path.

## Scope the mapping

* Pin `sub` to a single IAM role ARN whenever possible.
* Keep **Allowed Audiences** aligned with the audience passed to `GetWebIdentityToken`.
* Prefer separate Virtual Accounts for production and non-production roles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.