AWS - TrueFoundry Docs

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 (sts:GetWebIdentityToken). EKS pods can instead use a projected service-account token and the Kubernetes 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.

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 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:

aws iam enable-outbound-web-identity-federation

Allow the role to mint tokens

{
  "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):

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

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

Virtual Account — Claims

identity_provider_mapping:
  - identity_provider: aws-outbound-federation
    claims:
      sub: arn:aws:iam::123456789012:role/truefoundry-gateway

Agent — Subject (YAML key is still claims)

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

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 or APIs. Full exchange details: Workload Identity Federation.

EKS alternative

If the workload is only an EKS pod and you prefer projected service-account tokens, use the Kubernetes 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.

​Prerequisites

​Configure AWS (outbound web identity)

​Enable outbound federation

​Allow the role to mint tokens

​Issuer URL for your account

​Mint a token in the workload

​Configure TrueFoundry

​Exchange and call TrueFoundry

​EKS alternative

​Scope the mapping