Skip to content

Run agents on Amazon Bedrock AgentCore

Let an agent in AgentCore Runtime authenticate to Keycard with its execution role's AWS token, with no secret in the agent.

Amazon Bedrock AgentCore Runtime runs each agent under an IAM execution role, and AWS STS can give that role a signed token. Keycard accepts that token the same way it accepts any deployed workload’s token, so the agent gets Keycard tokens without holding a secret.

  1. Your agent Calls STS GetWebIdentityToken with its execution role’s credentials.
  2. AWS STS Returns a JWT whose iss is your account’s issuer and whose sub is the role’s ARN.
  3. Your agent Sends that JWT to Keycard as its client assertion.
  4. Keycard Matches the issuer and subject to a Workload Identity credential, and issues an access token for the Resource the agent asked for.

Outbound identity federation is off by default. Turn it on once for the AWS account, then read the account’s issuer URL:

Terminal window
aws iam enable-outbound-web-identity-federation
aws iam get-outbound-web-identity-federation-info --query IssuerIdentifier --output text

The issuer looks like https://<issuer-id>.tokens.sts.global.api.aws. Every role in the account gets tokens from the same issuer. You can also turn the feature on in the IAM console under Account settings.

Register the account’s issuer as a Provider

Section titled “Register the account’s issuer as a Provider”

If Keycard already has a Provider for this issuer, skip this section.

  1. Add the Provider

    In Keycard Console, navigate to Providers → Add Provider:

    Field Value
    Name A label, for example AWS <account-name>
    Issuer URL The issuer from the previous step, exactly as printed

    Leave Client ID and Client Secret empty. Keycard discovers the account’s signing keys from the issuer’s OpenID Connect discovery document.

Each AWS account has its own issuer, so add a Provider for every account your agents run in.

Add this statement to the runtime’s execution role. Its condition lets the role get tokens for Keycard and no other audience:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GetWebIdentityToken",
"Effect": "Allow",
"Action": "sts:GetWebIdentityToken",
"Resource": "*",
"Condition": {
"ForAllValues:StringEquals": {
"sts:IdentityTokenAudience": ["<keycard-issuer-url>"]
},
"Null": {
"sts:IdentityTokenAudience": "false"
}
}
}
]
}

Use your Keycard Issuer URL from Settings → Connection, with no trailing slash, as <keycard-issuer-url>. It must match the audience the agent requests below exactly.

With ForAllValues and the Null check, the role gets a token only when it names at least one audience and every audience it names is your Keycard issuer URL. AWS’s policy example uses ForAnyValue, which would also allow a token for Keycard and another service together. A plain StringEquals never matches, because sts:IdentityTokenAudience is a list, and STS then refuses every request.

For example, save it as web-identity.json and run:

Terminal window
aws iam put-role-policy --role-name <execution-role-name> \
--policy-name keycard-web-identity --policy-document file://web-identity.json

Then print the role’s ARN. It is the sub of the role’s tokens and the subject of its credential in Keycard:

Terminal window
aws iam get-role --role-name <execution-role-name> --query Role.Arn --output text
  1. Create an Application for the agent

    In Keycard Console, navigate to Applications → Add Application and name it after the agent. Fill in its required Identifier as well, such as urn:<agent-name>, because Access Policies name the Application by its identifier. Don’t generate a client ID and secret for it.

  2. Add a Workload Identity credential

    On the Application’s Application Credentials tab, click Add credential and choose Workload Identity:

    Field Value
    Provider The Provider for your account’s issuer
    Subject The execution role’s ARN, arn:aws:iam::<account-id>:role/<execution-role-name>

    Console marks Subject optional. Set it anyway, because a credential with no subject matches no token. Use the exact ARN, not a wildcard such as arn:aws:iam::<account-id>:role/*, which every role in the account would match.

Then give the Application access the same way as any agent that acts as itself. For MCP tools behind a Gateway, that is an Access Policy that names the Application’s identifier, as Autonomous Agent Access describes. To allow some of a Gateway’s tools and deny others, see Allow or deny specific tools.

The agent asks STS for a token, then exchanges it with Keycard. In AgentCore Runtime, boto3 finds the execution role’s credentials on its own. This Python example uses boto3 and httpx:

Terminal window
pip install "boto3>=1.41" httpx
import os
import boto3
import httpx
# The audience must match the IAM condition exactly, which has no trailing slash.
KEYCARD_ISSUER = os.environ["KEYCARD_ISSUER"].rstrip("/")
AWS_REGION = os.environ["AWS_REGION"]
# GetWebIdentityToken isn't served on the STS global endpoint.
sts = boto3.client("sts", region_name=AWS_REGION, endpoint_url=f"https://sts.{AWS_REGION}.amazonaws.com")
aws_token = sts.get_web_identity_token(
Audience=[KEYCARD_ISSUER],
SigningAlgorithm="RS256",
)["WebIdentityToken"]
response = httpx.post(
f"{KEYCARD_ISSUER}/oauth/2/token",
data={
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": aws_token,
"resource": os.environ["KEYCARD_RESOURCE_URL"],
},
headers={"User-Agent": "<agent-name>"},
)
response.raise_for_status()
access_token = response.json()["access_token"]

Set these as the runtime’s environment variables:

Variable Value
AWS_REGION The AWS Region the runtime runs in
KEYCARD_ISSUER Your Keycard Issuer URL, from Settings → Connection
KEYCARD_RESOURCE_URL The Resource the agent needs a token for, such as a Gateway’s MCP Access URL

Request a fresh STS token for each exchange, then send the access token to the Resource as a bearer token. The Keycard request needs no client ID, because Keycard finds the Application from the token’s issuer and subject.

Invoke the agent, then open its Application in Keycard Console and select the Activity tab. Each credential Keycard issued to the agent’s Application is listed there.

In the Audit Log, the agent’s own token requests name its Application as the actor. A tool call through a Gateway names the Gateway’s Application as the actor and the agent’s Application as the identity it acted for.

To see a refusal, cut the agent off: its next token request fails with invalid_client.

To stop one agent, delete its Workload Identity credential on the Application’s Application Credentials tab. Its next token request fails with invalid_client. Through a Gateway, a token it already holds stops working on its next call too, because each Gateway call is a new exchange, and Keycard refuses a token whose credential no longer exists.

A token it holds for a Resource that verifies tokens itself, such as another AgentCore runtime, keeps working until it expires (see Revoke access). To restore the agent, add the credential again with the same Provider and subject.

  1. In Keycard Console, delete the agent’s Workload Identity credential and its Application.
  2. In AWS, remove the sts:GetWebIdentityToken statement from the execution role. Turn outbound identity federation off only if nothing else in the account uses it.
  • Each execution role is one Application. The token’s subject is the role’s ARN, not the runtime’s or the session’s, so every runtime that uses the role signs in as the same Application, and their access and records can’t be told apart. Give each agent that needs its own identity its own execution role.
  • The agent holds no secret, so the execution role is what to guard. Anyone who can run code as the role signs in as this Application.
  • A token the agent holds for a Resource that checks tokens itself, such as another AgentCore runtime, keeps working until it expires, even after you cut the agent off.

invalid_client: No token application credential configured for provider ‘…’ and subject ‘…’

Section titled “invalid_client: No token application credential configured for provider ‘…’ and subject ‘…’”

Keycard has no Workload Identity credential for the issuer and subject in the token. The message shows both exactly as Keycard read them from the token, so compare them with the Provider’s Issuer URL and the credential’s Subject. The subject is the role’s ARN, never an assumed-role session ARN. A role in a different AWS account has a different issuer and needs that account’s Provider.

OutboundWebIdentityFederationDisabledException (listed as OutboundWebIdentityFederationDisabled in the STS API reference) means the feature is off in the account the execution role belongs to: run aws iam enable-outbound-web-identity-federation there. An access-denied error saying no identity-based policy allows sts:GetWebIdentityToken means the execution role lacks the statement above, or the agent asked for an audience its condition doesn’t list. The agent’s Audience must equal <keycard-issuer-url> in the condition exactly, trailing slash included. Call the regional STS endpoint, because the global endpoint doesn’t serve this API.

Did this recipe work for you?