> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mixlayer.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mixlayer.com/_mcp/server.

# AWS Workload Identity

> Authenticate AWS workloads with an STS-issued OIDC token

AWS outbound identity federation lets an IAM principal request a short-lived OIDC JWT from AWS Security Token Service. Mixlayer verifies that AWS-issued token and exchanges it for a short-lived Mixlayer access token.

For Amazon EKS, use the [Kubernetes projected-token guide](/workload-identity-kubernetes) instead.

## 1. Enable outbound identity federation

Enable the feature once for the AWS account:

```bash
aws iam enable-outbound-web-identity-federation
```

Retrieve the account-specific issuer URL:

```bash
export AWS_WIF_ISSUER=$(
  aws iam get-outbound-web-identity-federation-info \
    --query IssuerIdentifier \
    --output text
)
```

AWS hosts OIDC discovery and public signing keys under this issuer.

## 2. Allow the workload to request tokens

Grant `sts:GetWebIdentityToken` to the IAM role used by the workload. Restrict the audience and token lifetime:

**`file=`**

```json file=mixlayer-wif-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "sts:IdentityTokenAudience": "https://api.mixlayer.com"
        },
        "NumericLessThanEquals": {
          "sts:DurationSeconds": 300
        }
      }
    }
  ]
}
```

Attach this policy to a dedicated role rather than sharing a broad application role across unrelated workloads.

## 3. Inspect an AWS identity token

Request a token from a regional STS endpoint:

```bash
export MIXLAYER_WIF_AUDIENCE="https://api.mixlayer.com"

export MIXLAYER_SUBJECT_TOKEN=$(
  aws sts get-web-identity-token \
    --region "$AWS_REGION" \
    --audience "$MIXLAYER_WIF_AUDIENCE" \
    --signing-algorithm RS256 \
    --duration-seconds 300 \
    --query WebIdentityToken \
    --output text
)
```

`GetWebIdentityToken` is not available from the STS global endpoint. Decode one sample token locally and record its exact `iss`, `aud`, and `sub` claims. Do not paste production tokens into a web-based decoder or write them to logs.

## 4. Configure the Mixlayer provider

Create an OIDC provider in [Workload Identity](https://console.mixlayer.com/app/workload-identity):

| Setting          | Value                                  |
| ---------------- | -------------------------------------- |
| Issuer URI       | The account-specific `$AWS_WIF_ISSUER` |
| Allowed audience | `https://api.mixlayer.com`             |
| JWKS source      | OIDC discovery                         |

Map the AWS principal:

```text
mixlayer.subject = assertion.sub
```

Set the admission condition to the exact `sub` observed in the dedicated role's token:

```cel
mixlayer.subject == "arn:aws:iam::123456789012:role/mixlayer-production"
```

AWS-specific values such as principal tags are nested under the `https://sts.amazonaws.com/` claim. Map a tag with CEL bracket notation only after verifying its shape in a real token:

```text
attribute.environment = assertion["https://sts.amazonaws.com/"]["principal_tags"]["environment"]
```

Use `true` as the final authorization rule and grant only the permissions the role needs.

## 5. Exchange and use the AWS token

**`file=`**

```bash file=exchange-aws-workload-identity.sh
MIXLAYER_ACCESS_TOKEN=$(
  jq -n \
    --arg provider "$MIXLAYER_IDENTITY_PROVIDER_ID" \
    --arg token "$MIXLAYER_SUBJECT_TOKEN" \
    '{
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
      subject_token: $token,
      identity_provider_id: $provider
    }' |
  curl --fail-with-body --silent --show-error \
    https://api.mixlayer.com/v1/workload_identity/token \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -er .access_token
)

curl https://mixlayer.ai/v1/models \
  -H "Authorization: Bearer $MIXLAYER_ACCESS_TOKEN"
```

Request a new AWS token and exchange again before the Mixlayer token expires. AWS tokens can last from 60 to 3,600 seconds; a short lifetime such as 300 seconds limits exposure.

> **Warning**
>
> Do not send SigV4 requests, AWS access keys, or temporary STS credentials as
> the subject token. Mixlayer expects the signed JWT returned by
> `GetWebIdentityToken`.