AWS bedrock-agentcore high security documentation change
Summary
Added documentation for restricting IAM SigV4 invocation to AgentCore Gateway, restructured steps to include gateway configuration, expanded allowedWorkloadConfiguration security feature with implementation details, and added gateway invocation examples.
Security assessment
The changes explicitly add security documentation for restricting runtime access to approved gateways using resource-based policies and workload identity validation. This prevents unauthorized direct access to the runtime, mitigating potential security risks from confused deputy attacks or unauthorized API calls.
Diff
diff --git a/bedrock-agentcore/latest/devguide/runtime-oauth.md b/bedrock-agentcore/latest/devguide/runtime-oauth.md index 5d1305ecb..758c11b55 100644 --- a//bedrock-agentcore/latest/devguide/runtime-oauth.md +++ b//bedrock-agentcore/latest/devguide/runtime-oauth.md @@ -7 +7 @@ -JWT inbound authorization and OAuth outbound access samplePrerequisitesStep 1: Create your agent projectStep 2: Set up AWS Cognito user pool and add a userStep 3: Deploy your agentStep 4: Use bearer token to invoke your agentOAuth Error ResponsesStep 5: Set up your agent to access tools using OAuthStep 6: (Optional) Propagate a JWT token to AgentCore RuntimeTroubleshooting +Restrict IAM (SigV4) inbound invocation to your gatewayJWT inbound authorization and OAuth outbound access samplePrerequisitesStep 1: Create your agent projectStep 2: Set up AWS Cognito user pool and add a userStep 3 (Optional): Front your runtime with an AgentCore GatewayStep 4: Deploy your agentStep 5: Use bearer token to invoke your agentOAuth Error ResponsesStep 6: Set up your agent to access tools using OAuthStep 7: (Optional) Propagate a JWT token to AgentCore RuntimeTroubleshooting @@ -97,0 +98,2 @@ An AgentCore Runtime can support either IAM SigV4 or JWT Bearer Token based inbo + * Restrict IAM (SigV4) inbound invocation to your gateway + @@ -106 +108,3 @@ An AgentCore Runtime can support either IAM SigV4 or JWT Bearer Token based inbo - * Step 3: Deploy your agent + * Step 3 (Optional): Front your runtime with an AgentCore Gateway + + * Step 4: Deploy your agent @@ -108 +112 @@ An AgentCore Runtime can support either IAM SigV4 or JWT Bearer Token based inbo - * Step 4: Use bearer token to invoke your agent + * Step 5: Use bearer token to invoke your agent @@ -112 +116 @@ An AgentCore Runtime can support either IAM SigV4 or JWT Bearer Token based inbo - * Step 5: Set up your agent to access tools using OAuth + * Step 6: Set up your agent to access tools using OAuth @@ -114 +118 @@ An AgentCore Runtime can support either IAM SigV4 or JWT Bearer Token based inbo - * Step 6: (Optional) Propagate a JWT token to AgentCore Runtime + * Step 7: (Optional) Propagate a JWT token to AgentCore Runtime @@ -120,0 +125,40 @@ An AgentCore Runtime can support either IAM SigV4 or JWT Bearer Token based inbo +## Restrict IAM (SigV4) inbound invocation to your gateway + +You can front your AgentCore Runtime with an AgentCore Gateway so that the gateway becomes the single, governed entry point to the runtime — giving you policy-based authorization, Amazon Bedrock Guardrails, request and response interceptors, and unified observability, all applied outside the agent’s own environment. For the full rationale and how to set this up, see [Front your runtime with an AgentCore Gateway](./runtime-security-best-practices.html#security-bp-front-with-gateway). + +But this is only useful if callers can’t reach the runtime directly bypassing the gateway. If your runtime uses the default IAM (SigV4) inbound authorization, you can restrict invocation to the gateway so that traffic reaches the runtime only through it. To achieve this, attach a resource-based policy to the runtime that restricts invocation to your gateway’s execution role. The gateway assumes its service role to sign requests to the runtime, so the gateway role is the principal that invokes the runtime. Allow that role, and add an explicit `Deny` for every other principal so that no other identity can invoke the runtime even with a permissive identity-based policy. For more information about resource-based policies on runtimes, see [Resource-based policies for Amazon Bedrock AgentCore](./resource-based-policies.html). + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowOnlyGatewayRole", + "Effect": "Allow", + "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" }, + "Action": "bedrock-agentcore:InvokeAgentRuntime", + "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID" + }, + { + "Sid": "DenyOtherPrincipals", + "Effect": "Deny", + "Principal": { "AWS": "*" }, + "Action": "bedrock-agentcore:InvokeAgentRuntime", + "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID", + "Condition": { + "ArnNotEquals": { + "aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" + } + } + } + ] + } + +###### Tip + +An explicit `Deny` always overrides any `Allow`, including identity-based policies in the same account. Keying the `Deny` on `aws:PrincipalArn` ensures that only your gateway’s execution role can invoke the runtime, regardless of what other permissions exist in your account. + +###### Important + +Restricting the runtime to the gateway’s execution role is only as strong as the controls on who can assume that role. Any principal that can assume the gateway execution role can invoke the runtime as if it were the gateway. Lock the role down by adding `aws:SourceArn` and `aws:SourceAccount` conditions to the **gateway execution role’s** trust policy so that only your gateway can assume it. The [Confused deputy prevention](./runtime-security-best-practices.html#security-bp-confused-deputy) guidance shows the same technique applied to a runtime’s execution role; apply the same pattern here, but set the trust policy on the gateway execution role and scope `aws:SourceArn` to your gateway ARN. + @@ -267 +311,9 @@ This script creates a Cognito user pool, a user pool client, adds a user, and ge -## Step 3: Deploy your agent +## Step 3 (Optional): Front your runtime with an AgentCore Gateway + +You can front your AgentCore Runtime with an AgentCore Gateway so that the gateway becomes the single, governed entry point to the runtime — giving you policy-based authorization, Amazon Bedrock Guardrails, request and response interceptors, and unified observability, all applied outside the agent’s own environment. For the full rationale and how to set this up, see [Front your runtime with an AgentCore Gateway](./runtime-security-best-practices.html#security-bp-front-with-gateway). + +If you want to front this runtime, [create the gateway](./gateway-create.html) now, before you deploy the runtime in the next step. After you deploy, you’ll [add the runtime as a gateway target](./gateway-target-http-runtime.html). + +To make sure callers can’t bypass the gateway, restrict the runtime to accept invocations only from that gateway. You configure this in the next step, as part of the authorizer, using `allowedWorkloadConfiguration` (see allowedWorkloadConfiguration: restrict invocation to your gateway). + +## Step 4: Deploy your agent @@ -309,0 +362 @@ allowedAudience | aud | One of the values in aud claim from the token should m +allowedWorkloadConfiguration | `internal` | Optional. At launch, used to allow only your AgentCore Gateway to invoke the runtime. See Restrict invocation to your gateway. @@ -313 +366 @@ If both client_id and aud is provided, the agent runtime authorizer will verify -### Allowed workload configuration +### allowedWorkloadConfiguration: restrict invocation to your gateway @@ -315 +368 @@ If both client_id and aud is provided, the agent runtime authorizer will verify -You can optionally configure `allowedWorkloadConfiguration` on the `customJWTAuthorizer` to restrict which workloads in the request’s identity chain are allowed to invoke the target. This is useful when your AgentCore Runtime is invoked through an AgentCore Gateway and you want to ensure only specific gateways can reach the runtime. +The `allowedWorkloadConfiguration` field on the `customJWTAuthorizer` restricts which workloads in the request’s identity chain are allowed to invoke the runtime. Set the allowed workload to your gateway so that the runtime accepts a request only when its identity chain includes that gateway — this is how an OAuth (JWT) runtime enforces that traffic arrives only through the gateway you set up in Step 3. @@ -317 +370 @@ You can optionally configure `allowedWorkloadConfiguration` on the `customJWTAut -The `allowedWorkloadConfiguration` object contains: +You provide the allowed workloads using either of the following fields. You can specify one or both — a request is accepted if its identity chain matches an entry in **either** field, so you don’t need to provide both. @@ -319 +372 @@ The `allowedWorkloadConfiguration` object contains: - * **hostingEnvironments** – A list of hosting environments whose workloads are allowed to invoke the target. At launch, the only supported hosting environment is AgentCore Gateway. + * **hostingEnvironments** – A list of hosting environments whose workloads are allowed to invoke the target. Each entry is an object with an `arn`. At launch, the only supported hosting environment is AgentCore Gateway, so each `arn` must be an AgentCore Gateway ARN. @@ -321 +374 @@ The `allowedWorkloadConfiguration` object contains: - * **workloadIdentities** – A list of workload identities that are allowed to invoke the target. + * **workloadIdentities** – A list of workload identity names that are allowed to invoke the target. A workload identity name is **not** an ARN. It is the final segment of the gateway’s workload identity ARN, which you can find in the `workloadIdentityDetails` field of the `GetGateway` response. For example, if `workloadIdentityDetails.workloadIdentityArn` is `arn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-gateway-workload-identity`, then the workload identity name is `my-gateway-workload-identity`. @@ -326 +379 @@ The `allowedWorkloadConfiguration` object contains: -The following example creates an agent runtime with `allowedWorkloadConfiguration` that restricts invocation to a specific AgentCore Gateway: +The following example creates an agent runtime that restricts invocation to a specific AgentCore Gateway by its ARN. Specifying `hostingEnvironments` alone is the simplest way to allow a gateway: @@ -339,3 +391,0 @@ The following example creates an agent runtime with `allowedWorkloadConfiguratio - ], - "workloadIdentities": [ - "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id" @@ -347,0 +398,14 @@ The following example creates an agent runtime with `allowedWorkloadConfiguratio +Alternatively, you can identify the gateway by its workload identity name, or specify both fields. When both are present, a request is allowed if it matches an entry in either field. The following `allowedWorkloadConfiguration` snippet allows two different gateways — one identified by its ARN and one by its workload identity name: + + + "allowedWorkloadConfiguration": { + "hostingEnvironments": [ + { + "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id" + } + ], + "workloadIdentities": [ + "my-gateway-2-workload-identity" + ] + } + @@ -351,0 +416,4 @@ At launch, `allowedWorkloadConfiguration` is supported only for AgentCore Runtim +### Create and deploy the agent runtime + +With your authorizer configuration ready, create and deploy the agent runtime. The following examples show how to do this with the AgentCore CLI or the AWS SDK for Python (Boto3). Note the agent runtime ARN from the output — you’ll need it to invoke the agent in the next step. + @@ -357 +425 @@ AgentCore CLI - 1. [#deploy-agent.title] **To configure and deploy your agent** +**To configure and deploy your agent** @@ -359 +427 @@ AgentCore CLI - 2. Create your agent project with the AgentCore CLI: + 1. Create your agent project with the AgentCore CLI: @@ -365 +433 @@ When prompted, choose your framework (choose Strands Agents for this tutorial). - 3. Deploy your agent: + 2. Deploy your agent: @@ -369 +437 @@ When prompted, choose your framework (choose Strands Agents for this tutorial). - 4. Note the agent runtime ARN from the output. You’ll need this in the next step. + 3. Note the agent runtime ARN from the output. You’ll need this in the next step. @@ -411 +479 @@ Python -## Step 4: Use bearer token to invoke your agent +## Step 5: Use bearer token to invoke your agent @@ -414,0 +483,4 @@ Now that your agent is deployed with JWT authorization, you can invoke it using +###### Note + +If you fronted your runtime with a gateway in Step 3, add the deployed runtime as a gateway target before you invoke — see [AgentCore Runtime targets](./gateway-target-http-runtime.html) — and then invoke through the gateway endpoint shown in the examples that follow, rather than the runtime endpoint. + @@ -463 +536,8 @@ Use cURL - curl -v -X POST "${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT" \ + # If you fronted the runtime with a gateway (Step 3), the core endpoint URL is now your gateway URL + # export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://${GATEWAY_ID}.gateway.bedrock-agentcore.us-east-1.amazonaws.com/${TARGET_NAME}" + + export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT" + # If you fronted the runtime with a gateway (Step 3), the above works but there is also a simpler alternative: + # export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/invocations" + + curl -v -X POST "${INVOKE_URL}" \ @@ -498 +578 @@ Use Python - # Construct the URL + # Construct the URL — invoke the runtime directly @@ -500,0 +581,4 @@ Use Python + # If you are fronting the runtime with a gateway (see Step 3), invoke through + # the gateway target instead (replace GATEWAY_ID and my-target): + # url = f"https://GATEWAY_ID.gateway.bedrock-agentcore.{REGION_NAME}.amazonaws.com/my-target/invocations" + @@ -568 +652 @@ You must pre-register your OAuth client in Cognito (via AWS Console or CLI) to o -## Step 5: Set up your agent to access tools using OAuth +## Step 6: Set up your agent to access tools using OAuth @@ -576 +660 @@ For more information about setting up identity, see [Get started with AgentCore -### Step 5.1: Set up Credential Providers +### Step 6.1: Set up Credential Providers @@ -608 +692 @@ Make sure your invocation role has the necessary permissions for accessing the c -### Step 5.2: Enable agent to read Google Drive contents +### Step 6.2: Enable agent to read Google Drive contents @@ -659 +743 @@ AgentCore Identity Service stores the Google access token in the AgentCore Token -## Step 6: (Optional) Propagate a JWT token to AgentCore Runtime +## Step 7: (Optional) Propagate a JWT token to AgentCore Runtime @@ -663 +747 @@ Optionally, you can pass an Authorization header to an AgentCore Runtime to extr -### Step 6.1: Modify your agent code to read headers +### Step 7.1: Modify your agent code to read headers @@ -700 +784 @@ Modify the main agent file in your generated project (typically `src/main.py` or -### Step 6.2: Create the agent with request header allowlist +### Step 7.2: Create the agent with request header allowlist @@ -714 +798 @@ The AgentCore CLI creates the project structure and configuration files. Adjust -### Step 6.3: Invoke your agent +### Step 7.3: Invoke your agent