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 toolquery-docsof the targetcontext7iscontext7___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
-
In the Platform, go to Environment Settings > Authorizers and download the Amazon Bedrock AgentCore Gateway Authorizer. See Managing Authorizers for more information.
-
Unzip
plainid-agentcore-authz-bundle-<version>.zipand keep the folder structure. It contains:File Purpose plainid-agentcore-authz-<version>.zipThe Authorizer code. attach-plainid-agentcore-authz-<version>.zipThe helper that attaches the Authorizer to the gateway. *.sha256Checksums for the two ZIP files. plainid-agentcore-authz.yamlThe CloudFormation template. attach-cli/A command line tool for attaching and detaching manually. -
Verify both ZIP files. Each command must print
OK. On Linux withoutshasum, usesha256sum -c.shasum -a 256 -c plainid-agentcore-authz-<version>.zip.sha256 shasum -a 256 -c attach-plainid-agentcore-authz-<version>.zip.sha256 -
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:
- Deploy with
DiscoveryEnabledandTransactionalEnabledset tofalse. - Store the parameters from Step 3, using the
CredentialsKmsKeyArnoutput as the key. - 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
- Send
tools/listthrough an MCP client with a user token. Tools the caller may not use are missing from every page and from semantic search results. - Call a denied tool. The client receives HTTP 200 with a JSON-RPC error.
- 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:
ApproximateAgeOfOldestMessageon the queue (namespaceAWS/SQS), for example above 300 seconds.CollectorPostswithResult=dropped(namespacePlainID/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.
-
Upload the new ZIP files to your bucket, as in Step 1.
-
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 -
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
ModifyGatewayRoleset totrue, the invoke policy takes one of the role's managed policy slots. On a role at its limit, the install fails withLimitExceeded. To attach the policy as an inline policy instead, deploy withModifyGatewayRole=falseand runaws 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 toCollectorUrland 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.