# EKS IRSA: IAM role trust policy for a service account

IAM policy examples · Updated 17 November 2026

**Short answer:** The role trusts your cluster's OIDC provider with sts:AssumeRoleWithWebIdentity, and the conditions pin it to one Kubernetes service account: sub equals system:serviceaccount:<namespace>:<name> and aud equals sts.amazonaws.com. Then annotate the service account with the role ARN.

## The trust policy

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PaymentsApiServiceAccount",
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:payments:payments-api",
          "oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}
```

Replace the issuer ID with your cluster's, and attach the role's permissions (for example [DynamoDB](https://cloudconsole.dev/iam/dynamodb-one-table) or [S3](https://cloudconsole.dev/iam/s3-read-only-one-bucket)) as normal policies.

## What the conditions do

- **Federated principal**: tokens must be issued by this cluster's OIDC issuer, registered as an IAM identity provider in your account.
- **`:sub`**: Kubernetes puts `system:serviceaccount:<namespace>:<service-account>` in projected service account tokens. Matching it exactly means only pods using the `payments-api` service account in the `payments` namespace get the role.
- **`:aud`**: the audience the EKS pod identity webhook requests.

## Set it up

```
aws eks describe-cluster --name my-cluster \
  --query cluster.identity.oidc.issuer --output text

aws iam create-open-id-connect-provider \
  --url https://oidc.eks.eu-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE \
  --client-id-list sts.amazonaws.com

aws iam create-role --role-name payments-api \
  --assume-role-policy-document file://irsa-trust.json

kubectl annotate serviceaccount -n payments payments-api \
  eks.amazonaws.com/role-arn=arn:aws:iam::123456789012:role/payments-api
```

Restart the pods after annotating; the webhook only injects the token and environment variables when a pod is created.

## The newer alternative: EKS Pod Identity

EKS Pod Identity avoids per-cluster OIDC providers. The role trusts one service principal, and the mapping to a service account lives in EKS:

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EksPodIdentity",
      "Effect": "Allow",
      "Principal": {
        "Service": "pods.eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}
```

```
aws eks create-pod-identity-association --cluster-name my-cluster \
  --namespace payments --service-account payments-api \
  --role-arn arn:aws:iam::123456789012:role/payments-api
```

It needs the EKS Pod Identity Agent add-on on the cluster. Because the trust policy no longer names a cluster, the same role can be reused across clusters; scope it with session-tag conditions if that matters.

## Check from inside the pod

```
kubectl exec -n payments deploy/payments-api -- env | grep AWS_
# AWS_ROLE_ARN=arn:aws:iam::123456789012:role/payments-api
# AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
```

If these variables are missing, the webhook didn't mutate the pod: check the annotation and restart it.

## Common mistakes

- **`StringLike` with `system:serviceaccount:*`**: every service account in every namespace can assume the role.
- **Typo in the issuer ID**, or the provider registered in another account: errors say not authorized to perform `sts:AssumeRoleWithWebIdentity`.
- **Pods still using the node role**: the service account wasn't annotated before the pod started, or the pod spec uses a different service account.
- **Blocking IMDS** on nodes is still worth doing, so pods can't fall back to the node's instance role.

## Questions

### What is the sub claim for an EKS service account?

system:serviceaccount:<namespace>:<service-account-name>, for example system:serviceaccount:payments:payments-api.

### Should I use IRSA or EKS Pod Identity?

Pod Identity is simpler for new clusters: no OIDC provider per cluster and one trust policy shape. IRSA works everywhere, including clusters not on EKS-managed infrastructure that Pod Identity doesn't support.

## When this happens away from your desk

When a pod starts getting AccessDenied, the first check is which role it actually assumed. The CloudTrail AssumeRoleWithWebIdentity event shows that, and you can read it from a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [IAM roles for service accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
- [Learn how EKS Pod Identity grants pods access to AWS services](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html)

## Related

- [IAM role trust policy: examples and how it works](https://cloudconsole.dev/iam/assume-role-trust-policy)
- [GitHub Actions OIDC: IAM role trust policy](https://cloudconsole.dev/iam/github-actions-oidc)
- [AccessDenied: User is not authorized to perform: sts:AssumeRole](https://cloudconsole.dev/errors/not-authorized-to-perform-sts-assumerole)
- [iam:PassRole: policy example and why it matters](https://cloudconsole.dev/iam/iam-passrole)
- [IAM policy: read and write one DynamoDB table](https://cloudconsole.dev/iam/dynamodb-one-table)
- [ABAC: tag-based access control policy example](https://cloudconsole.dev/iam/abac-tags)

---

Source: https://cloudconsole.dev/iam/eks-irsa-trust-policy

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
