Amazon Bedrock 付款 AgentCore 的安全性

以下最佳实践可以帮助您在使用 Amazon Bedrock AgentCore 付款时防止安全事件。预防性控制措施可在不安全的行为发生之前将其阻止。Detective 控制表面意外活动，因此你可以对其做出反应。

预防性控制机制

使用这些控件来限制您的代理可以做什么，并将敏感材料拒之门外。

使用五角色 IAM 模式强制执行最低权限

AgentCore payments 使用不同的 IAM 角色将控制平面与数据平面分开。根据与每个角色匹配的角色设置 IAM 权限。在这种模式下，任何一个角色都不能既提高预算又可以用它来支出。

#	角色	用途
1	`ControlPlaneRole`	管理服务。
2	`ManagementRole`	配置会话。此角色已被明确拒绝`ProcessPayment`。
3	`ProcessPaymentRole`	执行付款。
4	`ResourceRetrievalRole`	Service-assumed。获取会话和凭证状态。
5	`AWSMarketplaceManageSubscriptions`（开启`ControlPlaneRole`）	对于 Coinbase，请将账户订阅市场列表。针对管理员的 Amazon 托管策略，而不是单独的可假设角色。

有关更多信息，请参阅用于 AgentCore 付款的 IAM 角色。

在 “ AgentCore 身份” 中存储凭证

切勿在代理代码或环境变量中嵌入钱包提供商凭证。

将 Coinbase CDP 或 Stripe（Privy）凭据存储在 Ident PaymentCredentialProvider ity 中。 AgentCore
该服务使用ResourceRetrievalRole在运行时检索它们。
按照钱包提供商的推荐时间表轮换凭证。如果凭证遭到泄露，请立即将其撤销。
对于使用快速创建创建的 Coinbase 连接器，凭据是服务管理的。轮换它们，RotatePaymentConnectorCredentials而不是在 Coinbase 开发者平台中生成密钥。有关更多信息，请参阅下一部分。

有关更多信息，请参阅 AgentCore 身份。

轮换服务管理的连接器凭证

当你使用 Quick create 创建 Coinbase 连接器时，P AgentCore ayments 会为你发放 Coinbase CDP API 密钥和钱包密钥，并将它们作为支付凭证提供者存储在 Identity 中， AgentCore 身份将秘密材料存储在 Secrets Manager 中。 Amazon 由于该服务拥有这些凭证，因此您可以按需将其替换为RotatePaymentConnectorCredentials，而无需登录 Coinbase 开发者平台或自己处理密钥材料。

一个连接器有两个服务管理的密钥，您可以出于不同的原因轮换每个密钥。轮换 API 密钥作为例行维护。只有在钱包密码被盗或丢失时才轮换钱包密码。有关更多信息，请参阅选择要轮换的凭据。

注意

您可以轮换来自控制台、 Amazon CLI 和 Amazon SDK 的证书。 AgentCore CLI 和 AgentCore SDK 不提供轮换命令，因此请使用其他三个命令之一。

检查连接器是否符合条件

轮换仅适用于服务管理其凭据的连接器。连接器的provisionMode字段会告诉你你处于哪种情况：

`provisionMode`	如何旋转
`QUICK_CREATE`	Amazon Bedrock AgentCore 配置了证书，因此这些凭证是服务管理的。调用 `RotatePaymentConnectorCredentials`。
`MANUAL`	您提供了凭证，因此您拥有这些证书。先向支付提供商轮换，然后使用新值`UpdatePaymentCredentialProvider`进行调用。

GetPaymentConnectorprovisionMode然后ListPaymentConnectors返回，是它的权威来源。 GetPaymentConnector还会返回credentialsUpdatedAt连接器当前的服务管理凭据生效的时间戳。该服务将此时间戳与初始配置时间一起播种，并在每次轮换时对其进行更新。用它来跟踪凭证年龄。MANUAL连接器没有。

在控制台provisionMode中，显示为创建类型列，显示快速创建或手动。你可以在以下地方找到它：

在 “付款” 页面上，展开付款管理器行以列出其连接器，然后检查连接器的创建类型列。
在付款管理器详情页面的付款连接器部分，选中创建类型列。
在连接器详细信息页面的付款身份验证部分，选中创建类型。本节还显示了上次凭证的轮换日期，该日期等同于控制台。credentialsUpdatedAt

选择要轮换的凭证

对于 Coinbase CDP 连接器，请使用具有以下一个或两个秘密的coinbaseCDP成员获credentialsToRotate取。这两个秘密的目的不同，风险也不同，因此出于不同的原因，将它们分开轮换。

Secret	什么时候轮换	它会影响什么
`API_KEY`	定期轮换 Coinbase CDP API 密钥 ID 和 API 密钥密钥作为例行维护，如果您怀疑密钥已泄露，请立即轮换。	API 密钥用于对向 Coinbase 发出的请求进行身份验证。Amazon Bedrock 会先 AgentCore 注册替换密钥，然后再删除之前的密钥，因此付款处理不会中断。
`WALLET_SECRET`	只有在钱包密码被泄露或丢失时才轮换钱包密码。它不是例行维护的一部分。	钱包密钥对钱包写入操作进行签名，因此轮换会影响交易签名。Coinbase取代了现有的钱包密码，而不是添加第二个密码，因此预计`ProcessPayment`通话最多可能在一分钟内失败。Coinbase CDP项目只有一个钱包密钥，因此轮换会影响使用相同项目的每个连接器。

轮换取代了连接器支付凭证提供商上的密码。每个使用相同支付身份验证的连接器都会受到影响，而不仅仅是您在请求中指定的连接器。

轮换的工作原理

旋转是同步的。该操作在返回响应之前完成轮换，并且一次只能轮换给定连接器的一组凭证。当密钥成功轮换时，新密钥会立即生效，连接器将保持该READY状态。当密钥轮换失败时，响应会包含错误，并且该密钥会保留其当前值。您可以重试请求。

响应返回连接器的标识符、其status（在成功轮换READY之后）和lastUpdatedAt：


{
  "paymentManagerId": "<paymentManagerId>",
  "paymentConnectorId": "<paymentConnectorId>",
  "status": "READY",
  "lastUpdatedAt": "2025-11-04T18:22:41.507000+00:00"
}

轮换后，致电GetPaymentConnector并确认credentialsUpdatedAt高级版。然后替换您在 Amazon Bedrock AgentCore 之外使用的先前密钥的任何副本。

RotatePaymentConnectorCredentials是等的。clientToken当您想安全地重试请求时，请提供一个，例如来自自动轮换任务的请求。使用相同的令牌重试会返回原始轮换的结果，而不是发布另一个密钥。

轮换 API 密钥

轮换 API 密钥作为例行维护。Amazon Bedrock在删除前一个密钥之前向Coinbase AgentCore 注册了替换密钥，因此在轮换进行期间，付款处理将继续进行。

例

Console

打开 Amazon Bedrock AgentCore 控制台。
在导航窗格的 “构建” 下，选择 “付款”。
选择拥有连接器的付款管理器。在 “付款连接器” 部分，选择连接器。
在连接器详细信息页面上，选择轮换凭据，然后选择轮换 API 密钥。

注意
只有使用快速创建创建的连接器才会显示@@ 轮换凭据。如果连接器使用您提供的凭证，请改用 Coinbase 进行轮换。有关更多信息，请参阅检查连接器是否符合条件。
在 “轮换 API 密钥” 对话框中，查看警告。轮换会删除当前的 API 密钥，并使用您与此付款身份验证关联的 Coinbase 账户创建新的密钥。所有使用此付款身份验证的连接器也会受到影响。
选择 “旋转”。控制台显示一条消息，说明轮换最多可能需要一分钟。轮换完成后，会显示一条成功消息，确认 API 密钥已轮换。

Amazon CLI

确认连接器符合条件，并记下其当前credentialsUpdatedAt值：


aws bedrock-agentcore-control get-payment-connector \
  --payment-manager-id <paymentManagerId> \
  --payment-connector-id <paymentConnectorId> \
  --region us-east-1

轮换 API 密钥：


aws bedrock-agentcore-control rotate-payment-connector-credentials \
  --payment-manager-id <paymentManagerId> \
  --payment-connector-id <paymentConnectorId> \
  --credentials-to-rotate '{"coinbaseCDP": {"secrets": ["API_KEY"]}}' \
  --region us-east-1

Amazon SDK


import boto3

client = boto3.client("bedrock-agentcore-control", region_name="us-east-1")

connector = client.get_payment_connector(
    paymentManagerId="<paymentManagerId>",
    paymentConnectorId="<paymentConnectorId>"
)

# Rotation applies only to connectors with service-managed credentials.
if connector.get("provisionMode") != "QUICK_CREATE":
    raise RuntimeError(
        "This connector uses credentials that you provided. Rotate them with the "
        "payment provider, and then call update_payment_credential_provider."
    )

response = client.rotate_payment_connector_credentials(
    paymentManagerId="<paymentManagerId>",
    paymentConnectorId="<paymentConnectorId>",
    credentialsToRotate={"coinbaseCDP": {"secrets": ["API_KEY"]}}
)

print(f"Status: {response['status']}")
print(f"Rotation completed at: {response['lastUpdatedAt']}")

轮换钱包密钥

只有在钱包密码被泄露或丢失时才轮换钱包密码。Coinbase CDP项目拥有一个钱包秘密，Coinbase将其取而代之，因此轮换会影响使用相同Coinbase CDP项目的每个连接器的交易签名。

重要

在电子钱包密钥轮换期间，ProcessPaymentAPI 预计会有长达一分钟的停机时间。在付款活动较少的时期内计划轮换，并确保您的代理可以优雅地处理失败的付款。

例

Console

打开 Amazon Bedrock AgentCore 控制台。
在导航窗格的 “构建” 下，选择 “付款”。
选择拥有连接器的付款管理器。在 “付款连接器” 部分，选择连接器。
在连接器详细信息页面上，选择轮换凭据，然后选择轮换钱包密码。
在轮换钱包密码对话框中，查看警告。轮换会删除当前的钱包密钥，并使用您与此付款身份验证关联的 Coinbase 账户创建一个新的钱包密钥。所有使用此付款身份验证的连接器也会受到影响。预计 ProcessPayment API 的停机时间长达一分钟。
选择 “旋转”。控制台显示一条消息，说明轮换最多可能需要一分钟。轮换完成后，将显示一条成功消息，确认钱包密钥已轮换。

Amazon CLI


aws bedrock-agentcore-control rotate-payment-connector-credentials \
  --payment-manager-id <paymentManagerId> \
  --payment-connector-id <paymentConnectorId> \
  --credentials-to-rotate '{"coinbaseCDP": {"secrets": ["WALLET_SECRET"]}}' \
  --region us-east-1

确认轮换后付款成功，因为钱包密钥会对每个钱包写入操作进行签名。

Amazon SDK


response = client.rotate_payment_connector_credentials(
    paymentManagerId="<paymentManagerId>",
    paymentConnectorId="<paymentConnectorId>",
    credentialsToRotate={"coinbaseCDP": {"secrets": ["WALLET_SECRET"]}}
)

print(f"Status: {response['status']}")
print(f"Rotation completed at: {response['lastUpdatedAt']}")

在一个请求中轮换两个密钥

您也可以在单个请求中列出这两个密钥。 AgentCore 然后，Amazon Bedrock 在同一个请求中将它们一个接一个地轮换，从 API 密钥开始，然后是电子钱包密钥。电子钱包密钥的停机时间考虑因素相同。

由于两次轮换是按顺序进行的，因此中途出现故障可能会导致 API 密钥已经轮换，而 Wallet 密钥会保留其当前值。响应会报告错误。重试请求以完成剩余的密钥。

要保持两个轮换的独立性，请为每个密钥发送单独的请求。这是控制台所完成的操作。

例

错误

错误	原因
`ValidationException`	该请求对该连接器无效。这包括选择连接器不使用的密钥，传递一个空的密钥列表，以及对您自己提供凭据的连接器调用操作。
`ConflictException`	此连接器已在进行轮换，或者该连接器未处于接受旋转的状态。等待连接器返回`READY`并重试。
`ResourceNotFoundException`	此账户和 Amazon 地区中不存在付款管理器或付款连接器。
`AccessDeniedException`	来电者无权致电`RotatePaymentConnectorCredentials`付款管理器。有关 AgentCore 付款，请参阅 IAM 角色。
`ThrottlingException`	请求已被阻止。使用指数回退进行重试。

有关完整的请求和响应架构，请参阅 API 参考RotatePaymentConnectorCredentials中的。

正确设置 UserId 标题

在 IAM-configured 入站授权付款管理器上，您的后端会声明X-Amzn-Bedrock-AgentCore-Payments-User-Id标题，而 AgentCore 付款不会对其进行验证。您有责任正确设置此值。

AgentCore payments 会验证 IAM 调用方和 JWT（使用 OAuth 时），但是 API 调用UserId标头的正确性由您负责。不要让最终用户或代理直接影响此标头。

安全的多租户部署

对于为多个最终用户提供服务的多租户部署，请在付款管理器中使用 CUSTOM_JWT (OAuth) 授权类型。这为服务提供了经过验证的最终用户身份。使用 IAM-configured 支付管理器， AgentCore 付款不会验证最终用户身份。

资金和授权是两个独立的最终用户决定，两者都是由代理商在带外做出的：

资金 — 最终用户通过钱包提供商门户网站存入资金。代理没有 API 访问资金的权限，也绝不能提示或自动启动资金。
委托 — 最终用户通过 Coinbase 支出权限或 Privy 委托操作授予权限。不要假设委托是永久性的，因为用户可以随时撤消委托。优雅地处理已撤销的委托。

将代理与支付工具隔离开来

代理不得访问卡号、CVV 值、银行详细信息或钱包私钥。代理人的观点停留在 “允许从用户拥有的钱包中消费”。

钱包密钥由提供商自行保管，而不是由开发者保管。 Amazon
切勿通过提示、工具输入或上下文窗口传递支付工具的详细信息。

在 Policy 中限制工具访问权限 AgentCore

要获得工具级授权，请通过 Amazon Bedrock AgentCore Gateway 公开付费终端节点。通过 Gateway 的每个呼叫都会被 Policy 拦截，Policy 是一个评估请求的 Cedar-based 引擎，包括代理的身份、工具名称和参数，并决定是否允许请求。 AgentCore

保单和付款会议涵盖不同的决定：

策略控制谁使用什么参数调用哪个工具。
付款会话控制可以花多少钱和持续多长时间。

它们共同为您提供正交杠杆，用于存放工具和支出金额。

编写以代理身份、用户组和请求参数为范围的 Cedar 策略。
拒绝不需要高成本工具的代理访问这些工具。
随着工具目录的变化，定期审查和审计政策。

有关更多信息，请参阅中的政策 AgentCore。

使用有预算限制和 TTL 的付款会话

每笔付款都是在有最大消费金额和到期时间的付款时段内进行的。基础设施层强制执行这些限制，因此即时注入和模型不确定性无法覆盖这些限制。

设置maxSpendAmount为任务所需的最低值，并设置一个短 TTL。
从保守的预算开始，只有在代理被证明是可靠的情况下才提高预算。
签约失败会自动撤销预算扣除额。

有关更多信息，请参阅创建付款会话。

验证和限制 PayTo 地址

该payTo地址指定了收款人的钱包。 AgentCore payments 不强制服务器端payTo限制，因此您的应用程序必须在调用 ProcessPayment API 之前验证地址。

维护预先验证的卖家地址的许可名单，并拒绝未知地址。
切勿让模型生成 PayTo 地址。它们必须来自可信来源，例如 x402 付款申请或经过验证的注册表。
处理 x402 回复时，对照预期的卖家进行验证。
最好使用 AgentCore 网关来发现端点，因为它通过 x402 Bazaar 提供经过验证payTo的地址。
应用 Cedar 政策来限制代理可以支付哪些地址。
不要跨会话缓存地址。请务必使用当前卖家提供的地址，并根据您的许可名单进行验证。
收件人筛选。会话限制限制了代理可以花多少钱，而不是可以向谁付款。使用钱包政策拒绝向特定收款人付款。对于 Stripe（Privy），请按照 Privy 网站上的付款制裁筛选指南进行操作。Coinbase会根据OFAC的制裁名单自动筛选所有交易。
使用支付提供商政策来限制钱包操作，例如签名和转账。欲了解更多信息，请参阅Privy网站上的 Stripe（Privy）政策文档以及Coinb ase网站上的Coinbase安全和政策文档。

安全的网络接入

使用 VPC 终端节点防止流量进入公共互联网。
应用终端节点策略和 IAM 条件 (aws:sourceVpc,aws:sourceVpce) 来限制来源。
Amazon CloudTrail 为所有 AgentCore 付款 API 调用启用。

为付款失败和回滚而设计

实现等性以防止重试时重复付款。
使用明确的回退行为来处理付款失败。不要无限期地重试。
监控部分故障并实施补偿交易。

侦测性控制

使用这些控件来观察支付活动和表面异常情况，以便您可以对其做出响应。

启用可观察性和审计日志

AgentCore payments 通过 Amazon CloudWatch 提供自动可观察性：

Vended logs — 记录每个数据平面呼叫（谁、什么、多少、给谁）。
销售跨度 — 中提供了完整的付款生命周期跟踪。 Amazon X-Ray
为异常支出模式设置警报，例如向未列出的地址付款、异常多的不同收款人或已知商家的地址突然更改。
根据您的合规要求保留日志。
不要依赖代理代码来记录自己的操作。

有关更多信息，请参阅 Amazon CloudWatch 的可观察性。

定期检查配置

审计预算并降低支出不足的代理的限额。
每季度审查 Cedar 政策和 IAM 角色。
监控钱包提供商仪表板，了解意外的委托或资金活动。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

可观测性

静态加密