Configuring Amazon Bedrock AgentCore

Prev Next

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 <gateway-id> \
      --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 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 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 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 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-<version>.zip.sha256
    shasum -a 256 -c attach-plainid-agentcore-authz-<version>.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://<your-bucket> --region <gateway-region>
    aws s3 cp plainid-agentcore-authz-<version>.zip s3://<your-bucket>/
    aws s3 cp attach-plainid-agentcore-authz-<version>.zip s3://<your-bucket>/
    

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/<gateway-id>
# existing: your key ARN
KEY=arn:aws:kms:<region>:<account>:key/<key-id>
# create: the key the stack created (run after Step 5)
KEY=$(aws cloudformation describe-stacks --stack-name plainid-agentcore-authz-<gateway-id> \
  --query "Stacks[0].Outputs[?OutputKey=='CredentialsKmsKeyArn'].OutputValue" --output text)

Store the Scope credentials:

aws ssm put-parameter --name $P/client_id --type String --value <client-id>
aws ssm put-parameter --name $P/client_secret --type SecureString --key-id $KEY --value <client-secret>

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-<gateway-id> \
  --template-file plainid-agentcore-authz.yaml --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
  --parameter-overrides GatewayIdentifier=<gateway-id> GatewayServiceRoleName=<role-name> \
    CodeBucket=<your-bucket> CodeKey=plainid-agentcore-authz-<version>.zip \
    PdpUrl=https://<tenant>.<region>.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-<gateway-id> \
  --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-<gateway-id> \
      --template-file plainid-agentcore-authz.yaml --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND \
      --parameter-overrides CodeKey=plainid-agentcore-authz-<new-version>.zip
    
  3. Confirm the gateway runs the new code. The last two commands must print the same value.

    aws lambda get-alias --function-name <function-name> --name live --query FunctionVersion --output text
    aws lambda get-function --function-name <function-name>:live --query Configuration.CodeSha256 --output text
    openssl dgst -sha256 -binary plainid-agentcore-authz-<new-version>.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 <function-name> --name live --function-version <n>

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-<gateway-id>

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 <key-arn> --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 <gateway-id> --lambda-arn <InterceptorAliasArn> --region <gateway-region>
python3 attach_cli.py detach --gateway <gateway-id> --lambda-arn <InterceptorAliasArn> --region <gateway-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.

© 2026 PlainID LTD. All rights reserved.