Skip to content
Latest (currently 2026.11.0) has the newest features, bug fixes, and CVE patches of Solo Enterprise for agentgateway.

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

AWS AssumeRole chaining

Enterprise
Page as Markdown

Sign requests to an AWS service with credentials from a chain of assumed IAM roles, such as a role in another AWS account.

About role chaining

An AWS role chain is a sequence of IAM roles that the gateway assumes one after another, in the following order.

  1. The ambient credentials of the gateway assume the first role in the chain.
  2. The AWS Security Token Service (STS) returns temporary credentials for that role.
  3. The temporary credentials of that role assume the next role in the chain. Steps 2 and 3 repeat for each remaining role.
  4. The credentials of the last role sign the requests to the backend with AWS Signature Version 4.

Use a chain when the gateway cannot assume the target role directly. For example, the target role might be in another AWS account and trust only an intermediate role, or a third party might require an external ID for its role.

To assume a single role, you can use the auth.aws.assumeRole field that the AWS backend authentication guide describes. The entAws field in this guide is a separate, enterprise-only alternative to auth.aws, and you cannot set both on the same policy.

The gateway caches only the credentials of the last role. When those credentials expire, the gateway assumes every role in the chain again. AWS limits a session that is created through role chaining to a maximum of one hour.

Before you begin

  1. Follow the Get started guide to install agentgateway.

  2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. Get the external address of the gateway and save it in an environment variable.

    Tip

    Kind cluster? Kind does not support LoadBalancer services by default. To use this option with a Kind cluster, install and run cloud-provider-kind.

    export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
    echo $INGRESS_GW_ADDRESS  
    kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 8080:80

You also need the following AWS resources:

  • Ambient AWS credentials for the gateway, such as an EKS service account that is annotated for an IAM role. The credentials must be allowed to assume the first role in the chain.
  • Each IAM role in the chain. The trust policy of each role must allow the previous role to assume it and the permissions policy of the last role must allow the call to the AWS service.

Assume a chain of roles

Configure the gateway to assume each role in the chain and to sign the backend requests with the credentials of the last role.

  1. Create an EnterpriseAgentgatewayPolicy that sets backend.entAws.assumeRole.chain. The policy targets an AgentgatewayBackend named aws-backend for the AWS service, so replace the name with the name of your backend. The chain in the following example has two roles: first gateway-hop in one account, and then target-role in a second account, which requires an external ID.

    kubectl apply -f- <<EOF
    apiVersion: enterpriseagentgateway.solo.io/v1alpha1
    kind: EnterpriseAgentgatewayPolicy
    metadata:
      name: aws-assume-role-chain
      namespace: httpbin
    spec:
      targetRefs:
      - group: agentgateway.dev
        kind: AgentgatewayBackend
        name: aws-backend
      backend:
        entAws:
          serviceName: execute-api
          region: us-east-1
          assumeRole:
            sessionName: agentgateway
            chain:
            - roleArn: arn:aws:iam::111111111111:role/gateway-hop
            - roleArn: arn:aws:iam::222222222222:role/target-role
              externalId: partner-external-id
    EOF

    Review the following table to understand this configuration.

    FieldDescription
    entAws.serviceNameSigning service name, such as bedrock, bedrock-agentcore, or execute-api. A typed AWS backend can supply the name, in which case you can omit the field.
    entAws.regionSigning region, such as us-east-1. Set the field when the AWS service is in a different region from the gateway.
    entAws.secretRefSecret with an explicit access key, in the accessKey, secretKey, and optional sessionToken keys. Cannot be combined with assumeRole, because the source credentials for STS always come from the environment of the gateway.
    entAws.assumeRole.chainThe roles to assume, in order. Set at least one role. Cannot be combined with assumeRole.roleArn.
    entAws.assumeRole.chain[].roleArnARN of the IAM role to assume in this step of the chain.
    entAws.assumeRole.chain[].externalIdOptional external ID to pass to STS when the trust policy of this role requires sts:ExternalId. The value must be 2 to 1224 characters and match [\w+=,.@:/-].
    entAws.assumeRole.roleArn and entAws.assumeRole.externalIdA single role and its external ID, as an alternative to chain. Set exactly one of roleArn and chain.
    entAws.assumeRole.sessionNameStatic session name (RoleSessionName) for the last role, which appears in AWS CloudTrail and in the Cost and Usage Report. Omit the field and AWS generates a random name.
    entAws.assumeRole.sessionNameExpressionCEL expression that the gateway evaluates against each request to produce the session name, such as jwt.sub. Cannot be combined with sessionName. The standalone configuration file has no separate field for the expression, and sets it as expression inside sessionName instead.
    entAws.assumeRole.tagsSession tags for the last role. Each tag sets key, plus exactly one of value or expression. STS allows at most 50 tags for one role session.

    The session name and the session tags apply only to the last role in the chain, because the credentials of that role sign the backend requests. The intermediate roles use a generated session name.

  2. Check the Accepted and Attached conditions of the policy.

    kubectl get enterpriseagentgatewaypolicy aws-assume-role-chain -n httpbin \
      -o jsonpath='{range .status.ancestors[*].conditions[*]}{.type}={.status}{"\n"}{end}'

    Example output:

    Accepted=True
    Attached=True
    
  3. Interpret the conditions. Accepted=True means that the policy is valid. Attached is True only when a route sends traffic to the backend that the policy targets, so an Attached=False condition usually means that no route uses the aws-backend backend yet.

Troubleshoot

Most configuration mistakes in the entAws field fail at kubectl apply time, because CEL validation rules in the CRD reject an invalid policy before the gateway receives it. STS errors in the chain appear only at request time, in the proxy logs.

SymptomCause and fix
The API server rejects the policy with exactly one of the fields in [roleArn chain] must be set.Set either assumeRole.roleArn for one role or assumeRole.chain for a chain, not both.
The API server rejects the policy with externalId must be set on each chain hop, not on the top-level assumeRole config.Move externalId into the chain entry for the role whose trust policy requires it.
The API server rejects the policy with secretRef and assumeRole are mutually exclusive.Remove secretRef, and give the ambient identity of the gateway permission to assume the first role.
The API server rejects the policy with at most one of the fields in [auth workloadIdentity tokenExchange entTokenExchange entCrossAppAccess entAws entConnector] may be set.Remove auth.aws or any other backend authentication method from the same policy.
Requests to the backend fail after the policy is attached.Check the proxy logs for the STS error. Each role must trust the previous role in the chain, and the first role must trust the ambient identity of the gateway.

Cleanup

You can remove the resources that you created in this guide.
kubectl delete enterpriseagentgatewaypolicy aws-assume-role-chain -n httpbin