在 Amazon Bedrock AgentCore Identity 中引用您自己的 AWS Secrets Manager 密钥

[人工智能](https://aws.amazon.com/blogs/machine-learning/)

AI 代理的能力取决于其可访问的工具。无论是从 CRM 中检索客户数据、向 Slack 发布更新，还是查询 GitHub 仓库，代理都需要调用外部 API，这意味着必须在运行时安全地传递凭证。正确实现这一点——避免在代码中硬编码密钥或在代理提示中暴露密钥——是构建生产级代理系统的关键挑战之一。

Amazon Bedrock AgentCore Identity 通过凭证提供程序和令牌库应对这一挑战：它会自动为每个出站凭证提供程序资源在您的账户中创建并管理一个位于 AWS Secrets Manager 的密钥。该密钥包含 API 密钥或客户端密钥，以及外部身份提供者的其他元数据。虽然 AgentCore Identity 完全负责创建和管理这些密钥，但客户此前无法在创建时配置自定义标签、轮换策略或使用 客户托管的 AWS Key Management Service (AWS KMS) 密钥进行加密。

今天，我们很高兴宣布，现在您可以在 AgentCore Identity 中引用 AWS Secrets Manager 中的密钥，从而引用您自己预先配置的密钥，并完全掌控其管理方式。借助此功能，您可以将组织现有的密钥治理流程扩展到 AgentCore。您可以提供一个已存在且预先配置好的 AWS Secrets Manager 密钥，用于您的 凭证提供程序 资源。您仍可完全控制其加密配置、轮换、复制、标签和资源策略，就像管理 Secrets Manager 中的其他密钥一样。您还可以选择同一 AWS 区域内另一个 AWS 账户中的密钥（不支持跨区域共享）。此外，该功能也支持通过 AWS Secrets Manager 外部连接器导入的密钥，从而实现与第三方密钥管理系统的集成。

在本文中，我们将回顾示例应用场景，并逐步指导您如何使用现有密钥配置凭证提供程序资源。

示例应用场景

以下是几个典型的应用场景：

1. 您的代理需要访问团队已有密钥的外部 API：直接向凭证提供程序资源提供该现有密钥的 ARN，而非让 AgentCore Identity 创建新密钥。您也可以引用同一区域内另一 AWS 账户中的密钥，同时支持通过 AWS Secrets Manager 外部连接器导入的密钥，便于与第三方密钥管理系统集成。
2. 您希望按安全最佳实践轮换密钥，同时确保代理持续正常工作：当您轮换密钥值时，AgentCore Identity 会在下一次读取时自动获取更新后的值，无需更新或重建凭证提供程序资源。
3. 您希望限制密钥访问范围，仅限于预期的代理用途：直接在 AWS Secrets Manager 中配置密钥的资源策略，控制哪些 AWS Identity and Access Management (IAM) 主体可以访问该密钥，并设置访问条件。
4. 您的代理运行在受监管环境中，要求所有凭证必须使用客户托管密钥加密：在提供给 AgentCore Identity 之前，先使用客户托管的加密密钥创建密钥。如果您的组织强制执行 SCP 和 RCP 以确保所有数据均使用客户托管 CMK 加密，此功能尤其有用。通过引用现有密钥，您的加密配置将被完整保留。
5. 您的组织要求对密钥添加资源标签，用于成本分摊、合规追踪或治理审计：在提供给 AgentCore Identity 之前，按照您的标准创建并标记密钥。

如需了解更多可用的密钥配置选项，请参阅 AWS Secrets Manager 用户指南。

前提条件

要跟随本文操作，您需要具备以下条件：

1. 一个已存在的 AWS Secrets Manager 密钥，其中包含 API 密钥或 OAuth 客户端密钥。
2. IAM 权限，允许 AgentCore Identity 服务主体 secretsmanager:GetSecretValue 访问该密钥。
3. 如果您使用的是客户托管的 AWS KMS 密钥，则需授予服务主体对该密钥的 kms:Decrypt 权限。
4. 可访问 Amazon Bedrock AgentCore Identity 控制台或 AWS 命令行界面 (AWS CLI)。

开始使用

要在 AWS Secrets Manager 中引用密钥，请在通过 AgentCore Identity API 创建凭证提供程序资源时提供密钥 ARN 和 JSON 键。AgentCore Identity 将在运行时从您指定的密钥中提取对应 JSON 键的凭证值。

以下部分将介绍如何通过 AWS 管理控制台、AWS CLI 或 AI 代理创建带有引用密钥的凭证提供程序资源。

使用控制台

您可以在 Amazon Bedrock AgentCore Identity 控制台中直接创建新的凭证提供程序资源时配置引用密钥。该功能支持 API 密钥和 OAuth 客户端凭证两种类型。

_图 1：AgentCore Identity 控制台，创建引用密钥的出站认证资源。_

A. 添加引用密钥的 API 密钥

要添加引用密钥的 API 密钥，请完成以下步骤：

1. 打开 Amazon Bedrock AgentCore 控制台。
2. 在左侧导航窗格中，选择 Identity。
3. 在 Outbound Auth 部分，选择 Add Outbound Auth。
4. 选择 Add API key。
5. 为您的出站认证资源输入一个 Name。
6. 在 API key selection method 下，选择 Provide API key via Secrets Manager。
7. 在 Secrets Manager ARN 字段中，输入或选择您现有密钥的 ARN。列表将显示您账户中可用的密钥。例如：arn:aws:secretsmanager:us-east-1:123456789012:secret:myApiKeySecret-AbCdEf。
8. 在 JSON key 字段中，指定 Secrets Manager 密钥内包含 API 密钥值的键。
9. 选择 Add。
10. 通过检查该凭证提供程序是否出现在 Outbound Auth 列表中，确认其已成功创建。

_图 2：AgentCore Identity 控制台，从 Secrets Manager 添加 API 密钥。_

B. 添加引用密钥的 OAuth 客户端密钥

要添加引用密钥的 OAuth 客户端密钥，请完成以下步骤：

1. 从 Identity 页面，选择 Add Outbound Auth。
2. 选择 Add OAuth client。
3. 为您的 OAuth 客户端输入一个 Name（例如，google-oauth-client-v5fz5）。
4. 在 Provider 下，选择您计划使用的内置或自定义提供商。
5. 输入身份提供商分配给您的 Client ID。
6. 在 Client secret 下，选择 Provide Client secret via Secrets Manager。
7. 在 Secrets Manager ARN 字段中，输入包含 OAuth 客户端密钥的密钥的 ARN。
8. 在 JSON key 字段中，指定密钥内包含客户端密钥值的键。
9. 选择 Add OAuth Client。
10. 通过检查该凭证提供程序是否出现在 Outbound Auth 列表中，确认其已成功创建。

_图 3：AgentCore Identity 控制台，从 Secrets Manager 添加 OAuth 客户端密钥。_

使用 AWS CLI

您可以在 AWS CLI 中直接为 OAuth 客户端密钥创建新的出站认证资源时配置引用密钥，如下所示：

aws bedrock-agentcore-control create-oauth2-credential-provider \
    --name "google-oauth-client-v5fz5" \
    --credential-provider-vendor "GoogleOauth2" \
    --oauth2-provider-config-input '{
        "googleOauth2ProviderConfig": {
            "clientId": "<clientId>",
            "clientSecretSource": "EXTERNAL",
            "clientSecretConfig": {
                "secretId": "arn:aws:secretsmanager:us-east-1:123456789012:secret:myGoogleKeySecret-AbCdEf",
                "jsonKey": "key"
            }
        }
    }'

Bash

在桌面使用 AI 代理

如果您正在使用 AI 编码代理（如 Kiro 或类似工具），您可以提示它直接配置引用密钥：

_“我在 AWS Secrets Manager 中有一个现有密钥，ARN 为 arn:aws:secretsmanager:us-east-1:123456789012:secret:my-api-key。请在 Amazon Bedrock AgentCore Identity 中创建一个名为 <client-name> 的 OAuth2 凭证提供程序，使用 GoogleOauth2 作为供应商。客户端 ID 为 <clientId>，客户端密钥来源为 EXTERNAL，密钥 JSON 键为 key。”_

注意：请将 <client-name> 和 <clientId> 替换为您的实际值。

重要提示：请通过向密钥添加资源策略，授予 AgentCore Identity 读取密钥的权限，允许服务主体调用 secretsmanager:GetSecretValue。如果您的密钥使用客户管理的 KMS 密钥加密，还需授予服务主体对该密钥的 kms:Decrypt 权限。

总结

借助引用 AWS Secrets Manager 中密钥的能力，AgentCore Identity 使您能够在为 AI 代理配置出站认证时灵活使用现有的密钥和密钥管理实践。您可继续完全掌控凭证的加密、轮换和访问方式，而 AgentCore Identity 将负责在运行时检索这些凭证。

如需开始使用，请参阅 Amazon Bedrock AgentCore Identity 文档。有关密钥管理的更多信息，请参阅 AWS Secrets Manager 用户指南。

• * *

关于作者