--- title: "Configuring Amazon Bedrock AgentCore" slug: "configuring-amazon-bedrock-agentcore" updated: 2026-11-15T17:26:56Z published: 2026-11-15T17:26:56Z canonical: "docs.plainid.io/configuring-amazon-bedrock-agentcore" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.plainid.io/llms.txt > Use this file to discover all available pages before exploring further. # Configuring Amazon Bedrock AgentCore This page walks through installing the Authorizer on an existing Amazon Bedrock AgentCore Gateway with the PlainID CloudFormation template, including: - Staging the code - Storing the credentials - Choosing settings - Deploying the stack - Verifying enforcement The stack installs everything in your AWS account and attaches the Authorizer to the gateway as its last step. You install one stack per gateway. After installation, you change settings with a stack update and credentials in AWS Systems Manager Parameter Store, without touching the gateway. ## Prerequisites Before you start, ensure you have: - An Amazon Bedrock AgentCore Gateway, and its gateway ID and service role. To read both, run: ``` aws bedrock-agentcore-control get-gateway --gateway-identifier \ --query '{id:gatewayId,role:roleArn,url:gatewayUrl}' ``` The role name is the last segment of the role ARN. If the ARN includes a path, such as `arn:aws:iam::<account>:role/service-role/<role-name>`, note the path (`/service-role/`) as well. The default role the console creates uses `/service-role/`. - A PlainID Environment with access to the PDP (Runtime) endpoint. - A Scope in PlainID with a Client ID and Client Secret. See [Managing Scopes](/v1/docs/managing-scopes) for more information. - An Asset Type for MCP tools (by default `Tools`) and Policies that grant access to it. Each Asset's path is the tool name exactly as the gateway exposes it: the target name, three underscores, then the tool name. For example, the tool `query-docs` of the target `context7` is `context7___query-docs`. See [Tools and MCP](/v1/docs/mcp-policy-builder-controls) for more information. - The AWS CLI version 2, configured for the gateway's account and Region. Version 1 mishandles values that start with `https://`. - For MCP discovery or transactional reporting, an AWS Bedrock AgentCore Gateway POP and its client certificate, and your PlainID collector endpoint URL. See [POP Setup](/v1/docs/bedrock-agentcore-pop-setup) for more information. Create every resource on this page in the same account and Region as the gateway. ## Step 1: Download and Stage the Package 1. In the Platform, go to **Environment Settings** > **Authorizers** and download the **Amazon Bedrock AgentCore Gateway** Authorizer. See [Managing Authorizers](/v1/docs/managing-authorizers) for more information. 2. Unzip `plainid-agentcore-authz-bundle-<version>.zip` and keep the folder structure. It contains: | File | Purpose | | --- | --- | | `plainid-agentcore-authz-<version>.zip` | The Authorizer code. | | `attach-plainid-agentcore-authz-<version>.zip` | The helper that attaches the Authorizer to the gateway. | | `*.sha256` | Checksums for the two ZIP files. | | `plainid-agentcore-authz.yaml` | The CloudFormation template. | | `attach-cli/` | A command line tool for attaching and detaching manually. | 3. Verify both ZIP files. Each command must print `OK`. On Linux without `shasum`, use `sha256sum -c`. ``` shasum -a 256 -c plainid-agentcore-authz-.zip.sha256 shasum -a 256 -c attach-plainid-agentcore-authz-.zip.sha256 ``` 4. Upload both ZIP files to an Amazon S3 bucket in the gateway's Region. Keep them side by side under the same prefix, because the template locates the helper by adding `attach-` to the Authorizer's file name. ``` aws s3 mb s3:// --region aws s3 cp plainid-agentcore-authz-.zip s3:/// aws s3 cp attach-plainid-agentcore-authz-.zip s3:/// ``` ## Step 2: Choose the Encryption Key The Authorizer stores its secrets as `SecureString` parameters in Parameter Store. Choose which AWS KMS key encrypts them with the `CredentialsKeyMode` stack parameter: | Mode | What it means | | --- | --- | | `create` (default) | The stack creates a customer managed key for you, with automatic yearly rotation, and returns its ARN as the `CredentialsKmsKeyArn` output. You store the parameters after the deploy, because the key exists only then. | | `existing` | You use your own symmetric customer managed key in the gateway's Region (multi-Region keys work). Pass its key ARN as `CredentialsKmsKeyArn`. Aliases aren't accepted. | | `aws-managed` | Parameter Store uses the AWS managed key `aws/ssm`. Any principal in the account that can read the parameters can decrypt them, so IAM read access alone protects the secrets. | With `create` or `existing`, each function checks that its secrets use the stack's key and refuses them otherwise. Whoever stores the parameters needs `kms:Encrypt` on the key. ## Step 3: Store the Credentials The Authorizer reads its credentials from Parameter Store under the prefix `/plainid/agentcore/<gateway-id>/`. Set the key for your mode first: ``` P=/plainid/agentcore/ # existing: your key ARN KEY=arn:aws:kms:::key/ # create: the key the stack created (run after Step 5) KEY=$(aws cloudformation describe-stacks --stack-name plainid-agentcore-authz- \ --query "Stacks[0].Outputs[?OutputKey=='CredentialsKmsKeyArn'].OutputValue" --output text) ``` Store the Scope credentials: ``` aws ssm put-parameter --name $P/client_id --type String --value aws ssm put-parameter --name $P/client_secret --type SecureString --key-id $KEY --value ``` If you report to PlainID, also store the client certificate pair you downloaded from the POP: ``` aws ssm put-parameter --name $P/collector_cert_pem --type String --value file://collector-cert.pem aws ssm put-parameter --name $P/collector_key_pem --type SecureString --key-id $KEY \ --value file://collector-key.pem ``` With `aws-managed`, leave out `--key-id $KEY`. When you change a value later, run the same command with `--overwrite` and the same `--key-id`. Without a key ID, Parameter Store falls back to `aws/ssm`, and the key check refuses the parameter. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `client_id` | `String` | Yes | The Client ID from your PlainID Scope. | | `client_secret` | `SecureString` | Yes | The Client Secret from your PlainID Scope. | | `collector_cert_pem` | `String` | Only for reporting | The POP's client certificate, leaf certificate only. Store a certificate with a chain over 4 KB with `--tier Advanced`. | | `collector_key_pem` | `SecureString` | Only for reporting | The private key for that certificate. | The certificate pair affects reporting only. A missing or invalid pair never blocks authorization. To confirm which key encrypts each parameter, run: ``` aws ssm describe-parameters --parameter-filters "Key=Name,Option=BeginsWith,Values=$P/" \ --query 'Parameters[].[Name,Type,KeyId]' --output table ``` ## Step 4: Choose Your Settings You pass each setting as a stack parameter in Step 5. Only `PdpUrl` is required. The template validates every value before it changes anything. | Stack parameter | Default | Description | | --- | --- | --- | | `PdpUrl` | Empty | Your PDP Runtime base URL, for example `https://<tenant>.<region>.plainid.io/runtime`. Must use `https://` and end with `/runtime`. Required while `EnforcementEnabled` is `true`. | | `EnforcementEnabled` | `true` | `true` authorizes every `tools/call` and filters every `tools/list`. `false` passes every request and response through unchanged and never calls the PDP. | | `AuthenticationMethod` | `token` | `token` sends the caller's token to the PDP. `secret-header` also sends the Client Secret in an `X-Client-Secret` header. `secret-body` sends the Client Secret in the request body. The Authorizer always sends the Client ID. | | `UserAuthHeader` | `Authorization` | The request header that carries the caller's token. | | `TokenForwardHeaders` | Empty | A comma-separated list of extra request headers to forward to the PDP, for example `X-Agent-Token`. `x-client-id`, `x-client-secret`, and `content-type` are reserved. | | `McpResourceType` | `Tools` | The Asset Type for MCP tools in PlainID. | | `DiscoveryEnabled` | `false` | `true` reports the tools of every `tools/list` page and search result to PlainID, one record per gateway target, before filtering. | | `TransactionalEnabled` | `false` | `true` reports every tool call to PlainID, including the caller's token so PlainID can identify the calling agent. | | `CollectorUrl` | Empty | Your PlainID collector endpoint URL. Required when `DiscoveryEnabled` or `TransactionalEnabled` is `true`. | | `PdpTimeoutMs` | `3000` | The PDP request timeout in milliseconds, 100 to 7000. | | `CollectorTimeoutMs` | `1000` | The timeout of each report to PlainID in milliseconds, 100 to 5000. | | `AllowedSetTtlSeconds` | `30` | How long, in seconds, the Authorizer reuses a caller's allowed tool list between pages, 0 to 300. `0` turns reuse off. | | `CredentialsReloadSeconds` | `300` | How often, in seconds, the functions reload credentials from Parameter Store, 30 to 3600. | | `ConfigReloadCooldownSeconds` | `60` | After the PDP rejects the credentials (HTTP 401), the minimum time, in seconds, between immediate credential reloads, 5 to 3600. | | `McpErrorCode` | `-32603` | The JSON-RPC error code returned when the Authorizer blocks a call. An integer from `-32768` to `-32000`. | | `McpErrorMessage` | `Access Denied` | The JSON-RPC error message returned when the Authorizer blocks a call. Up to 200 characters. | Number values must be integers. The switches accept only `true` or `false`. ## Step 5: Deploy the Stack Run: ``` aws cloudformation deploy --stack-name plainid-agentcore-authz- \ --template-file plainid-agentcore-authz.yaml --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \ --parameter-overrides GatewayIdentifier= GatewayServiceRoleName= \ CodeBucket= CodeKey=plainid-agentcore-authz-.zip \ PdpUrl=https://..plainid.io/runtime ``` Add any setting from Step 4 to `--parameter-overrides`. For your own key, add `CredentialsKeyMode=existing CredentialsKmsKeyArn=$KEY`. For the AWS managed key, add `CredentialsKeyMode=aws-managed`. | Parameter | Default | Description | | --- | --- | --- | | `GatewayIdentifier` | Required | The gateway ID. It must match the **Gateway ID** of the gateway's POP. | | `GatewayServiceRoleName` | Required | The name of the gateway's service role, without the path or ARN. | | `GatewayServiceRolePath` | `/` | The role's IAM path, for example `/service-role/`. A wrong path fails the install with "principal arn provided does not match the actual principal arn". | | `ModifyGatewayRole` | `true` | `true` attaches an invoke policy to the gateway role. `false` returns the policy as the `GatewayRolePolicyJson` output for you to attach yourself (see Notes). | | `CodeBucket` | Required | The S3 bucket from Step 1. | | `CodeKey` | Required | The S3 key of the Authorizer ZIP. | | `CredentialsKeyMode` | `create` | See Step 2. | | `CredentialsKmsKeyArn` | Empty | Your key ARN, with `existing` only. | | `ConfigPrefix` | Empty | The Parameter Store prefix. Empty means `/plainid/agentcore/<gateway-id>/`. | | `LogLevel` | `INFO` | `DEBUG`, `INFO`, `WARN`, or `ERROR`. | **With `create`, install in this order:** 1. Deploy with `DiscoveryEnabled` and `TransactionalEnabled` set to `false`. 2. Store the parameters from Step 3, using the `CredentialsKmsKeyArn` output as the key. 3. To report to PlainID, turn the switches on with a stack update (see Changing the Configuration). The stack attaches the Authorizer when it deploys, so between steps 1 and 2 the gateway blocks every MCP request. The first request after you store the parameters succeeds. If the gateway already serves traffic, create a key first and install with `existing` instead. When the deploy finishes, the stack returns these outputs: | Output | Description | | --- | --- | | `CredentialsKmsKeyArn` | The key that encrypts the credentials (`create` and `existing`). | | `InterceptorFunctionName` | The Authorizer function. Use it for the commands on this page. | | `InterceptorAliasArn` | The function alias the gateway invokes. | | `InterceptorLogGroupName` | The Authorizer's CloudWatch log group. | | `CollectorQueueUrl`, `CollectorFunctionName` | The queue and function that report to PlainID. | | `GatewayRolePolicyJson` | The invoke policy, when `ModifyGatewayRole` is `false`. | | `DiscoveryRoleArn`, `DiscoveryExternalId` | The role PlainID uses to list the gateway's targets, and its External ID. Enter both in the POP. Returned only when `DiscoveryEnabled` is `true`. | ## Step 6: Verify 1. Send `tools/list` through an MCP client with a user token. Tools the caller may not use are missing from every page and from semantic search results. 2. Call a denied tool. The client receives HTTP 200 with a JSON-RPC error. 3. Call a permitted tool and it succeeds A blocked call returns this response, with the request's `id`: ``` {"jsonrpc": "2.0", "id": 7, "error": {"code": -32603, "message": "Access Denied", "data": {"source": "plainid-agentcore-authz", "reason": "deny"}}} ``` The Authorizer handles each MCP request as follows: | Request | What the gateway does | | --- | --- | | `tools/list` and semantic search | Returns only the tools the caller's Policies allow, on every page. | | `tools/call`, permitted | Forwards the call to the target. | | `tools/call`, denied, error, or timeout | Returns a JSON-RPC error with `McpErrorCode` and `McpErrorMessage`. | | Other methods, such as `initialize`, `ping`, prompts, and resources | Passes through unchanged. | ## Reporting to PlainID When you turn on `DiscoveryEnabled` or `TransactionalEnabled`, the Authorizer reports to your POP: | Switch | What the Authorizer reports | | --- | --- | | `DiscoveryEnabled` | The tools of each `tools/list` page and search result as the gateway returned them, before filtering. One record per gateway target. | | `TransactionalEnabled` | One record per tool call: timestamp, caller IP, gateway ID, target name, gateway URL, the request headers including the caller's token, the AWS identity the gateway verified (for AWS-signed requests), and the JSON-RPC request including the tool arguments. | The Authorizer never reports tool results, and doesn't report the gateway's built-in search tool or requests other than tool calls. The Authorizer sends each record to an Amazon SQS queue in your account, and a second function posts it to PlainID over mutual TLS. If a post fails, the function retries it twice, about three minutes apart, then drops it. Records wait in the queue for up to one day. A record can occasionally arrive twice. To monitor reporting, set alarms on: - `ApproximateAgeOfOldestMessage` on the queue (namespace `AWS/SQS`), for example above 300 seconds. - `CollectorPosts` with `Result=dropped` (namespace `PlainID/AgentCore`), above 0. ## Changing the Configuration **Settings.** Run a stack update with only the parameters that change. The stack keeps the rest. ``` aws cloudformation deploy --stack-name plainid-agentcore-authz- \ --template-file plainid-agentcore-authz.yaml --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \ --parameter-overrides EnforcementEnabled=false ``` Always send the template file. If you reuse the existing template (`--use-previous-template` or **Use existing template** in the console), the update succeeds but keeps the old values. The update takes one to three minutes and applies to all traffic at once. If it fails, CloudFormation rolls back the code and settings together. **Credentials.** Update a parameter with `put-parameter --overwrite`. Every function picks up the change within `CredentialsReloadSeconds`. When you rotate the Client Secret, the Authorizer picks up the new value on the first request the PDP rejects, so you can revoke the old secret right after you store the new one. ## Upgrading Each release ships under a new file name. 1. Upload the new ZIP files to your bucket, as in Step 1. 2. Update the stack with the new `CodeKey`: ``` aws cloudformation deploy --stack-name plainid-agentcore-authz- \ --template-file plainid-agentcore-authz.yaml --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \ --parameter-overrides CodeKey=plainid-agentcore-authz-.zip ``` 3. Confirm the gateway runs the new code. The last two commands must print the same value. ``` aws lambda get-alias --function-name --name live --query FunctionVersion --output text aws lambda get-function --function-name :live --query Configuration.CodeSha256 --output text openssl dgst -sha256 -binary plainid-agentcore-authz-.zip | base64 ``` To roll back, run the same update with the previous `CodeKey`. In an emergency, point the `live` alias at the previous version: ``` aws lambda update-alias --function-name --name live --function-version ``` The stack keeps earlier versions for rollback. Delete versions you no longer need with `aws lambda delete-function --function-name <function-name> --qualifier <n>`, but never the version `live` points at. ## Uninstalling ``` aws cloudformation delete-stack --stack-name plainid-agentcore-authz- ``` The stack removes only the PlainID interceptor from the gateway. Afterward, run `get-gateway` and confirm `interceptorConfigurations` is gone. The stack doesn't delete your Parameter Store parameters or the key it created. Delete the parameters yourself, and schedule the key's deletion when you no longer need it: ``` aws kms schedule-key-deletion --key-id --pending-window-in-days 7 ``` ## Troubleshooting Every blocked call carries a `data.reason`: | `data.reason` | Cause | What to do | | --- | --- | --- | | `deny` | Your Policies don't permit the tool. | Review the Policies for this identity and tool. | | `pdp_unreachable` | The PDP didn't answer in time or returned an error. | Check `PdpUrl`, network access to the PDP, and `PdpTimeoutMs`. | | `pdp_unauthorized` | The PDP rejected the credentials or the user's token. | Check the Client ID and Client Secret, and the caller's token. The `PdpUnauthorized` metric's `HasToken` dimension shows whether the request carried a token. | | `unparseable` | The Authorizer couldn't read the request or response. | Check the log for the request ID. | | `config` | A setting is invalid, a credential is missing, or a credential uses the wrong key. | The log names the setting or parameter. | The log group (`InterceptorLogGroupName` output) holds one JSON line per decision, with the decision, the reason, timings, and a request ID. The Authorizer never logs tokens or secrets. The Authorizer publishes metrics to CloudWatch in the namespace `PlainID/AgentCore`, including `Decisions`, `Latency`, `PdpLatency`, `PdpUnauthorized`, `ConfigRefreshFailures`, and, when reporting is on, `CollectorPosts`, `CollectorEnqueueFailures`, and `CollectorDroppedTools`. ### Attaching or Detaching Manually If the stack's attach step fails, for example because the deploying identity can't call `UpdateGateway`, fix the cause and attach with the tool in the `attach-cli` folder. The tool needs Python 3 and `boto3`, and permission for `bedrock-agentcore:GetGateway`, `bedrock-agentcore:UpdateGateway`, and `iam:PassRole` on the gateway role. ``` python3 attach_cli.py attach --gateway --lambda-arn --region python3 attach_cli.py detach --gateway --lambda-arn --region ``` Both commands are safe to run again. Don't call `UpdateGateway` yourself with partial arguments: it replaces the whole gateway configuration and resets every setting you leave out. If the tool or the stack reports `gateway has settings this installer does not know`, it left the gateway unchanged. Upgrade `boto3` (`pip install -U boto3`) for the tool, or use a newer Authorizer release for the stack. ## Notes - A gateway runs one interceptor per interception point, and the Authorizer uses both. If the gateway already has an interceptor, the stack refuses to install and leaves the gateway unchanged. Detach your interceptor first. - With `ModifyGatewayRole` set to `true`, the invoke policy takes one of the role's managed policy slots. On a role at its limit, the install fails with `LimitExceeded`. To attach the policy as an inline policy instead, deploy with `ModifyGatewayRole=false` and run `aws iam put-role-policy --role-name <role-name> --policy-name PlainIdInterceptorInvoke-<gateway-id> --policy-document '<GatewayRolePolicyJson>'`. - The Authorizer needs outbound HTTPS to `PdpUrl`, Amazon SQS, and Systems Manager. The reporting function needs outbound HTTPS to `CollectorUrl` and Systems Manager. In a VPC, use a NAT gateway or interface VPC endpoints. - The Authorizer reports records up to about 250 KB. It splits larger tool lists across several records and drops larger tool calls from reporting, without affecting the decision.