本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 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 角色](payments-iam-roles.md)。
### 在 “ AgentCore 身份” 中存储凭证
切勿在代理代码或环境变量中嵌入钱包提供商凭证。
+ 将 Coinbase CDP 或 Stripe（Privy）凭据存储在 Ident `PaymentCredentialProvider` ity 中。 AgentCore
+ 该服务使用`ResourceRetrievalRole`在运行时检索它们。
+ 按照钱包提供商的推荐时间表轮换凭证。如果凭证遭到泄露，请立即将其撤销。
+ 对于使用**快速**创建创建的 Coinbase 连接器，凭据是服务管理的。轮换它们，`RotatePaymentConnectorCredentials`而不是在 Coinbase 开发者平台中生成密钥。有关更多信息，请参阅下一部分。
有关更多信息，请参阅 [AgentCore 身份](identity.md)。
### 轮换服务管理的连接器凭证
当你使用 **Quick** create 创建 Coinbase 连接器时，P AgentCore ayments 会为你发放 Coinbase CDP API 密钥和钱包密钥，并将它们作为支付凭证提供者存储在 Identity 中， AgentCore 身份将秘密材料存储在 Secrets Manager 中。 Amazon 由于该服务拥有这些凭证，因此您可以按需将其替换为`RotatePaymentConnectorCredentials`，而无需登录 Coinbase 开发者平台或自己处理密钥材料。
一个连接器有两个服务管理的密钥，您可以出于不同的原因轮换每个密钥。轮换 API 密钥作为例行维护。只有在钱包密码被盗或丢失时才轮换钱包密码。有关更多信息，请参阅[选择要轮换的凭据](#payments-rotate-secrets)。
**注意**
您可以轮换来自控制台、 Amazon CLI 和 Amazon SDK 的证书。 AgentCore CLI 和 AgentCore SDK 不提供轮换命令，因此请使用其他三个命令之一。
#### 检查连接器是否符合条件
轮换仅适用于服务管理其凭据的连接器。连接器的`provisionMode`字段会告诉你你处于哪种情况：
| `provisionMode` | 如何旋转 |
| --- | --- |
| `QUICK_CREATE` | Amazon Bedrock AgentCore 配置了证书，因此这些凭证是服务管理的。调用 `RotatePaymentConnectorCredentials`。 |
| `MANUAL` | 您提供了凭证，因此您拥有这些证书。先向支付提供商轮换，然后使用新值`UpdatePaymentCredentialProvider`进行调用。 |
`GetPaymentConnector``provisionMode`然后`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": "",
"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 注册了替换密钥，因此在轮换进行期间，付款处理将继续进行。
**Example**
1. 打开 [Amazon Bedrock AgentCore 控制台](https://console.amazonaws.cn/bedrock-agentcore/)。
1. 在导航窗格的 “**构建**” 下，选择 “**付款**”。
1. 选择拥有连接器的付款管理器。在 “**付款连接器**” 部分，选择连接器。
1. 在连接器详细信息页面上，选择**轮换凭据**，然后选择**轮换 API 密钥**。
**注意**
只有使用**快速**创建创建的连接器才会显示@@ **轮换凭据**。如果连接器使用您提供的凭证，请改用 Coinbase 进行轮换。有关更多信息，请参阅[检查连接器是否符合条件](#payments-rotate-eligibility)。
1. 在 “**轮换 API 密钥**” 对话框中，查看警告。轮换会删除当前的 API 密钥，并使用您与此付款身份验证关联的 Coinbase 账户创建新的密钥。所有使用此付款身份验证的连接器也会受到影响。
1. 选择 “**旋转**”。控制台显示一条消息，说明轮换最多可能需要一分钟。轮换完成后，会显示一条成功消息，确认 API 密钥已轮换。
确认连接器符合条件，并记下其当前`credentialsUpdatedAt`值：
```
aws bedrock-agentcore-control get-payment-connector \
--payment-manager-id \
--payment-connector-id \
--region us-east-1
```
轮换 API 密钥：
```
aws bedrock-agentcore-control rotate-payment-connector-credentials \
--payment-manager-id \
--payment-connector-id \
--credentials-to-rotate '{"coinbaseCDP": {"secrets": ["API_KEY"]}}' \
--region us-east-1
```
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-east-1")
connector = client.get_payment_connector(
paymentManagerId="",
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="",
paymentConnectorId="",
credentialsToRotate={"coinbaseCDP": {"secrets": ["API_KEY"]}}
)
print(f"Status: {response['status']}")
print(f"Rotation completed at: {response['lastUpdatedAt']}")
```
#### 轮换钱包密钥
只有在钱包密码被泄露或丢失时才轮换钱包密码。Coinbase CDP项目拥有一个钱包秘密，Coinbase将其取而代之，因此轮换会影响使用相同Coinbase CDP项目的每个连接器的交易签名。
**重要**
在电子钱包密钥轮换期间，`ProcessPayment`API 预计会有长达一分钟的停机时间。在付款活动较少的时期内计划轮换，并确保您的代理可以优雅地处理失败的付款。
**Example**
1. 打开 [Amazon Bedrock AgentCore 控制台](https://console.amazonaws.cn/bedrock-agentcore/)。
1. 在导航窗格的 “**构建**” 下，选择 “**付款**”。
1. 选择拥有连接器的付款管理器。在 “**付款连接器**” 部分，选择连接器。
1. 在连接器详细信息页面上，选择**轮换凭据**，然后选择**轮换钱包密码**。
1. 在**轮换钱包密码**对话框中，查看警告。轮换会删除当前的钱包密钥，并使用您与此付款身份验证关联的 Coinbase 账户创建一个新的钱包密钥。所有使用此付款身份验证的连接器也会受到影响。预计 `ProcessPayment` API 的停机时间长达一分钟。
1. 选择 “**旋转**”。控制台显示一条消息，说明轮换最多可能需要一分钟。轮换完成后，将显示一条成功消息，确认钱包密钥已轮换。
```
aws bedrock-agentcore-control rotate-payment-connector-credentials \
--payment-manager-id \
--payment-connector-id \
--credentials-to-rotate '{"coinbaseCDP": {"secrets": ["WALLET_SECRET"]}}' \
--region us-east-1
```
确认轮换后付款成功，因为钱包密钥会对每个钱包写入操作进行签名。
```
response = client.rotate_payment_connector_credentials(
paymentManagerId="",
paymentConnectorId="",
credentialsToRotate={"coinbaseCDP": {"secrets": ["WALLET_SECRET"]}}
)
print(f"Status: {response['status']}")
print(f"Rotation completed at: {response['lastUpdatedAt']}")
```
#### 在一个请求中轮换两个密钥
您也可以在单个请求中列出这两个密钥。 AgentCore 然后，Amazon Bedrock 在同一个请求中将它们一个接一个地轮换，从 API 密钥开始，然后是电子钱包密钥。电子钱包密钥的停机时间考虑因素相同。
由于两次轮换是按顺序进行的，因此中途出现故障可能会导致 API 密钥已经轮换，而 Wallet 密钥会保留其当前值。响应会报告错误。重试请求以完成剩余的密钥。
要保持两个轮换的独立性，请为每个密钥发送单独的请求。这是 控制台所完成的操作。
**Example**
```
aws bedrock-agentcore-control rotate-payment-connector-credentials \
--payment-manager-id \
--payment-connector-id \
--credentials-to-rotate '{"coinbaseCDP": {"secrets": ["API_KEY", "WALLET_SECRET"]}}' \
--region us-east-1
```
```
response = client.rotate_payment_connector_credentials(
paymentManagerId="",
paymentConnectorId="",
credentialsToRotate={
"coinbaseCDP": {"secrets": ["API_KEY", "WALLET_SECRET"]}
}
)
```
#### 错误
| 错误 | 原因 |
| --- | --- |
| `ValidationException` | 该请求对该连接器无效。这包括选择连接器不使用的密钥，传递一个空的密钥列表，以及对您自己提供凭据的连接器调用操作。 |
| `ConflictException` | 此连接器已在进行轮换，或者该连接器未处于接受旋转的状态。等待连接器返回`READY`并重试。 |
| `ResourceNotFoundException` | 此账户和 Amazon 地区中不存在付款管理器或付款连接器。 |
| `AccessDeniedException` | 来电者无权致电`RotatePaymentConnectorCredentials`付款管理器。有关[ AgentCore 付款，请参阅 IAM 角色](payments-iam-roles.md)。 |
| `ThrottlingException` | 请求已被阻止。使用指数回退进行重试。 |
有关完整的请求和响应架构，请参阅 API 参考[RotatePaymentConnectorCredentials](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_RotatePaymentConnectorCredentials.html)中的。
### 正确设置 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](policy.md)。
### 使用有预算限制和 TTL 的付款会话
每笔付款都是在有最大消费金额和到期时间的付款时段内进行的。基础设施层强制执行这些限制，因此即时注入和模型不确定性无法覆盖这些限制。
+ 设置`maxSpendAmount`为任务所需的最低值，并设置一个短 TTL。
+ 从保守的预算开始，只有在代理被证明是可靠的情况下才提高预算。
+ 签约失败会自动撤销预算扣除额。
有关更多信息，请参阅[创建付款会话](payments-create-session.md)。
### 验证和限制 PayTo 地址
该`payTo`地址指定了收款人的钱包。 AgentCore payments 不强制服务器端`payTo`限制，因此您的应用程序必须在调用 `ProcessPayment` API 之前验证地址。
+ **维护预先验证的卖家地址的许可名单**，并拒绝未知地址。
+ **切勿让模型生成 PayTo 地址。**它们必须来自可信来源，例如 x402 付款申请或经过验证的注册表。
+ 处理 x402 回复时**，对照预期的卖家进行验证**。
+ **最好使用 AgentCore 网关**来发现端点，因为它通过 x402 Bazaar 提供经过验证`payTo`的地址。
+ **应用 Cedar 政策**来限制代理可以支付哪些地址。
+ **不要跨会话缓存地址。**请务必使用当前卖家提供的地址，并根据您的许可名单进行验证。
+ **收件人筛选。**会话限制限制了代理可以花多少钱，而不是可以向谁付款。使用钱包政策拒绝向特定收款人付款。对于 Stripe（Privy），请按照 Privy 网站上的[付款制裁筛选指南进行](https://docs.privy.io/recipes/agent-integrations/x402-sanctions-screening)操作。Coinbase会根据OFAC的制裁名单自动筛选所有交易。
+ **使用支付提供商政策**来限制钱包操作，例如签名和转账。欲了解更多信息，请参阅Privy网站上的 [Stripe（Privy）政策文档](https://docs.privy.io/controls/policies/overview)以及Coinb [ase网站上的Coinbase安全和政策文档](https://docs.cdp.coinbase.com/wallets/security-and-policies/security-overview)。
### 安全的网络接入
+ 使用 VPC 终端节点防止流量进入公共互联网。
+ 应用终端节点策略和 IAM 条件 (`aws:sourceVpc`,`aws:sourceVpce`) 来限制来源。
+ Amazon CloudTrail 为所有 AgentCore 付款 API 调用启用。
### 为付款失败和回滚而设计
+ 实现等性以防止重试时重复付款。
+ 使用明确的回退行为来处理付款失败。不要无限期地重试。
+ 监控部分故障并实施补偿交易。
## 侦测性控制
使用这些控件来观察支付活动和表面异常情况，以便您可以对其做出响应。
### 启用可观察性和审计日志
AgentCore payments 通过 Amazon CloudWatch 提供自动可观察性：
+ **Vended logs — 记录**每个数据平面呼叫（谁、什么、多少、给谁）。
+ **销售跨度** — 中提供了完整的付款生命周期跟踪。 Amazon X-Ray
+ 为异常支出模式设置警报，例如向未列出的地址付款、异常多的不同收款人或已知商家的地址突然更改。
+ 根据您的合规要求保留日志。
+ 不要依赖代理代码来记录自己的操作。
有关更多信息，请参阅 [Amazon CloudWatch 的可观察性](payments-observability.md)。
### 定期检查配置
+ 审计预算并降低支出不足的代理的限额。
+ 每季度审查 Cedar 政策和 IAM 角色。
+ 监控钱包提供商仪表板，了解意外的委托或资金活动。