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
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.
- The ambient credentials of the gateway assume the first role in the chain.
- The AWS Security Token Service (STS) returns temporary credentials for that role.
- The temporary credentials of that role assume the next role in the chain. Steps 2 and 3 repeat for each remaining role.
- 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
Follow the Get started guide to install agentgateway.
Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.
Get the external address of the gateway and save it in an environment variable.
Tip
Kind cluster? Kind does not support
LoadBalancerservices by default. To use this option with a Kind cluster, install and runcloud-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_ADDRESSkubectl 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.
Create an EnterpriseAgentgatewayPolicy that sets
backend.entAws.assumeRole.chain. The policy targets an AgentgatewayBackend namedaws-backendfor the AWS service, so replace the name with the name of your backend. The chain in the following example has two roles: firstgateway-hopin one account, and thentarget-rolein 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 EOFReview the following table to understand this configuration.
Field Description entAws.serviceNameSigning service name, such as bedrock,bedrock-agentcore, orexecute-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 optionalsessionTokenkeys. Cannot be combined withassumeRole, 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.roleArnandentAws.assumeRole.externalIdA single role and its external ID, as an alternative to chain. Set exactly one ofroleArnandchain.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 withsessionName. The standalone configuration file has no separate field for the expression, and sets it asexpressioninsidesessionNameinstead.entAws.assumeRole.tagsSession tags for the last role. Each tag sets key, plus exactly one ofvalueorexpression. 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.
Check the
AcceptedandAttachedconditions 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=TrueInterpret the conditions.
Accepted=Truemeans that the policy is valid.AttachedisTrueonly when a route sends traffic to the backend that the policy targets, so anAttached=Falsecondition usually means that no route uses theaws-backendbackend 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.
| Symptom | Cause 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