Amazon Bedrock AgentCore Identity 中 对 私 有 证 书 颁 发 机 构 的 支 持

公司动态 AWS 机器学习 原文语言:英文

许 多 构 建 应 用 程 序 的 团 队 在 内 部 自 托管 身 份 提 供 商 (IdP) , 例 如 Keycloak 或 PingFederate 。

全文

Amazon Bedrock AgentCore Identity 中的私有证书颁发机构支持

许多构建应用程序的团队在私有网络内部自托管其身份提供商 (IdP),例如 Keycloak 或 PingFederate。这些 IdP 通常提供来自私有证书颁发机构 (CA) 的 TLS 服务器证书。借助 Amazon Bedrock AgentCore 的一项功能——AgentCore Identity 中的私有 CA 支持,您的代理现在可以连接到这些 IdP,同时信任您的组织已经使用的私有 CA。

AgentCore Identity 现在支持用于私有身份提供商的私有 CA 证书。您将 PEM 编码的 CA 证书存储在 AWS Secrets Manager 或 Amazon Simple Storage Service (Amazon S3) 中,并在凭据提供商中对其进行引用。CA 证书仅包含公共证书,不包含其私钥。AgentCore Identity 使用它来验证您的 IdP 的发现、JSON Web 密钥集 (JWKS) 和令牌端点所呈现的服务器证书。CA 证书必须是根 CA 或中间 CA 证书。

在这篇文章中,我们将向您展示如何使用 AWS Private Certificate Authority 颁发 IdP 证书。然后,我们配置 AgentCore Identity 凭据提供商以信任该证书并轮换 CA,同时将停机时间降至最低。我们还展示了如何保护 CA 证书,以便只有您的 IdP 团队才能对其进行更改。尽管 AgentCore Identity 支持任何私有 CA(包括企业、第三方和自签名根 CA),但本文中的演练使用 AWS Private CA 和 Keycloak 作为 IdP。

方案概述

考虑一个需要调用由您的 Keycloak IdP 保护的内部 wiki API 的代理。该代理运行在 Amazon Bedrock AgentCore 的一项功能 AgentCore Runtime 上,该功能托管您的代理代码。为了从 Keycloak 获取 OAuth 2.0 访问令牌,代理使用 AgentCore Identity 凭据提供商,该提供商保存了 IdP 连接详细信息和客户端凭据。

下图展示了此设置。Keycloak 运行在您的虚拟私有云 (VPC) 中,位于内部应用程序负载均衡器后面。负载均衡器提供由 AWS Private CA 签名的 AWS Certificate Manager (ACM) 私有证书。AgentCore Identity 信任的 CA 证书存储在 Secrets Manager 或 Amazon S3 中。

AgentCore Identity 通过 Amazon VPC Lattice 私密地访问 IdP,Amazon VPC Lattice 通过资源网关(VPC Lattice 流量进入您的 VPC 的入口点)连接到您的 VPC。私有 CA 支持需要 VPC Lattice。如果您选择托管选项,AgentCore Identity 将为您创建和管理 VPC Lattice 资源。

图 1:将 AgentCore Identity 连接到使用私有 CA 的自托管 IdP

工作流程如下:

您将 CA 证书存储在 Secrets Manager 或 Amazon S3 中。

您创建一个指向您的 IdP 和 CA 证书的凭据提供商。

AgentCore Identity 读取 CA 证书并检查它是否是有效的 CA 证书。

您的代理向 AgentCore Identity 请求访问令牌。

AgentCore Identity 通过 VPC Lattice 连接到 IdP,并针对您的 CA 检查负载均衡器证书。

IdP 颁发令牌,AgentCore Identity 将其返回给您的代理。

使用机器到机器 (machine-to-machine)、代表 (on-behalf-of) 和用户委派流的代理也可以使用私有 CA,而无需更改其代码。

先决条件

要完成此演练,您需要:

一个能够访问 AgentCore 控制台的 AWS 账户,位于支持 AgentCore Identity 私有 IdP 的受支持 AWS 区域中。

一个运行在您的 VPC 中、符合 OpenID Connect (OIDC) 标准的自托管 IdP,并为您的代理注册了一个 OAuth 客户端。“连接到私有身份提供商”中描述了网络要求,包括子网、安全组和 IdP 主机名的私有托管区。

最新版本的 AWS 命令行界面 (AWS CLI) 和 OpenSSL。

创建凭据提供商的权限,以及对 CA 证书的读取访问权限。AgentCore Identity 使用调用 CreateOauth2CredentialProvider 的主体身份的凭据来读取证书,因此该主体需要对该密钥具有 secretsmanager:GetSecretValue 权限,或对该对象具有 s3:GetObject 权限。如果该密钥或对象使用客户管理的 AWS Key Management Service (AWS KMS) 密钥进行加密,则该主体还需具有该密钥的 kms:Decrypt 权限。

注意事项

在规划部署时,请记住以下几点:

仅限私有 IdP:凭证提供者或授权者必须拥有 privateEndpoint 才能使用私有 CA。否则,请求将失败,提示信息为 “The private certificate authority feature can only be used with private IdP.”

PEM 格式的 CA 证书:文件必须为 PEM 编码,且大小不超过 16 KB。文件只能包含在有效期内的根或中间 CA 证书。

每个提供者只能有一个证书来源:每个凭证提供者引用一个 secret 或一个 S3 对象。若要信任多个 CA,请将证书放在同一个 PEM 文件中。

存储位置:secret 或 S3 对象必须与凭证提供者位于同一 AWS 区域。Secrets Manager 的 secret 还必须与凭证提供者在同一账户中。S3 对象可以在其他账户,只要提供 bucketOwnerAccountId 并且 bucket 策略授予访问权限。

区域:私有 CA 支持取决于 VPC Lattice,并在 AgentCore Identity 支持私有 IdP 的 AWS 区域可用。

操作指南

本操作指南包含四个步骤。如果您的 IdP 已经提供来自企业 CA 的证书,请直接跳到第 2 步。

步骤 1:为您的 IdP 颁发服务器证书

首先在 AWS Private CA 中创建根 CA。有关说明,请参阅 “Create a private CA” 和 “Install the CA certificate”。请选择通用模式,因为短期证书模式会颁发有效期为 7 天或更短的证书。创建 CA 时,请授权 ACM 续订证书,以便 ACM 能在证书过期前为 IdP 的服务器证书续订。

接下来,请求服务器证书。AgentCore Identity 会检查证书是否匹配 IdP 主机名,因此请将出现在 IdP discovery 文档中的每个主机名都作为主题备用名称(SAN)包含进去。在大多数 Keycloak 部署中,discovery、JWKS 和 token 端点共享同一个主机名。例如,如果您的 discovery URL 为 https://keycloak.example.local/realms/agents/.well-known/openid-configuration,请将 keycloak.example.local 添加为 SAN。

在控制台为 IdP 请求私有证书

打开 ACM 控制台并选择 “Request”。

选择 “Request a private certificate”,然后点击 “Next”。

在 “Certificate authority” 中,选择您创建的 CA。

在 “Fully qualified domain name” 中,输入 IdP 主机名,例如 keycloak.example.local。

点击 “Request”。

将证书附加到位于 IdP 前端的内部负载均衡器的 HTTPS 监听器。有关说明,请参阅 “Update an HTTPS listener”。

步骤 2:存储 CA 证书

AgentCore Identity 需要信任 CA 证书以验证 IdP 的服务器证书。因为它信任的是 CA 而不是服务器证书本身,所以每次服务器证书续订时无需更新凭证提供者。

以 PEM 格式从 AWS Private CA 导出 CA 证书:

aws acm-pca get-certificate-authority-certificate \ --certificate-authority-arn arn:aws:acm-pca:us-east-1:111122223333:certificate-authority/11223344-1234-1122-2233-112233445566 \ --query Certificate \ --output text > idp-root-ca.pem

在上传文件之前,请检查其是否符合要求。文件必须为 PEM 编码并满足大小限制,只包含在有效期内的 CA 证书。以下命令显示 CA 标志、到期日期和文件大小。最后一个命令确认 IdP 的证书链指向此 CA。请在能够访问 IdP 的主机上运行它。当链有效时,它会返回 “Verify return code: 0 (ok)”。

openssl x509 -in idp-root-ca.pem -noout -subject -enddate openssl x509 -in idp-root-ca.pem -noout -text | grep "CA:TRUE" wc -c /dev/null | grep "Verify return code"

输出类似如下所示:

subject=CN=Example Corp Root CA notAfter=Nov 10 00:00:00 2035 GMT CA:TRUE 1489 Verify return code: 0 (ok)

将文件存储在 Secrets Manager 或 Amazon S3 中。Secrets Manager 的 secret 必须是字符串类型,并且与凭证提供者在同一账户中。S3 对象可以在其他账户,这适用于在中心账户中运行 IdP 的组织。

# 选项 A:AWS Secrets Manager aws secretsmanager create-secret \ --name agentcore/keycloak-root-ca \ --secret-string file://idp-root-ca.pem # 选项 B:Amazon S3 aws s3 cp idp-root-ca.pem s3://amzn-s3-demo-bucket/trust-anchors/keycloak-root-ca.pem

仅向运营您的 IdP 的团队授予对密钥或对象的写入访问权限。示例策略请参见本文后面的“保护 CA 证书”。

步骤 3:创建凭证提供程序

您可以在 AgentCore 控制台或使用 AWS CLI 创建凭证提供程序。私有 CA 设置仅在将 OAuth 客户端连接到 VPC 后才会出现在控制台上,因为私有 CA 支持仅适用于私有 IdP。

在控制台创建信任您私有 CA 的凭证提供程序(控制台)

打开 AgentCore 控制台,在导航窗格的“连接”下选择“出站身份验证”。然后选择“添加 OAuth 客户端”。

对于提供程序,选择“自定义提供程序”。对于配置类型,选择“发现 URL”,并输入您的 IdP 的发现 URL,例如 https://keycloak.example.local/realms/agents/.well-known/openid-configuration。然后输入客户端 ID 和客户端密钥。

展开“其他配置”。在 VPC 安全性下,选择“托管”,并选择能够访问 IdP 的 VPC、子网和安全组。如果您自行管理 VPC Lattice 资源,选择“自托管”,并改为选择资源配置。

在“根证书颁发机构”下,选择“添加根证书”。

在“添加根证书”面板中,证书来源选择“AWS Secrets Manager”,并选择您在步骤 2 中创建的密钥。若使用 Amazon S3,选择“Amazon S3”并输入 S3 URI。若对象位于其他账户,还需输入存储桶所有者账户 ID。

选择“应用”。

选择“添加 OAuth 客户端”。

根证书颁发机构字段可接受根证书或中间 CA 证书。

图 2:从 AWS Secrets Manager 添加根证书

要使用 AWS CLI 创建相同的凭证提供程序,请在自定义 OAuth 2.0 提供程序配置中添加 certificateConfigurations:

aws bedrock-agentcore-control create-oauth2-credential-provider \ --name keycloak-private-ca \ --credential-provider-vendor CustomOauth2 \ --oauth2-provider-config-input '{ "customOauth2ProviderConfig": { "oauthDiscovery": { "discoveryUrl": "https://keycloak.example.local/realms/agents/.well-known/openid-configuration" }, "clientId": "agentcore-client", "clientSecret": "", "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "securityGroupIds": ["sg-0abc123def456"], "endpointIpAddressType": "IPV4" } }, "certificateConfigurations": [ { "secretsManager": { "secretArn": "arn:aws:secretsmanager:us-east-1:111122223333:secret:agentcore/keycloak-root-ca-AbCdEf" } } ] } }'

若改用 Amazon S3,请将 certificateConfigurations 条目替换为 {"s3": {"uri": "s3://amzn-s3-demo-bucket/trust-anchors/keycloak-root-ca.pem", "bucketOwnerAccountId": "444455556666"}}。如果省略 bucketOwnerAccountId,AgentCore Identity 会假设存储桶在您自己的账户中。为避免在 shell 历史中泄露客户端密钥,您可以引用存储在 Secrets Manager 中的客户端密钥。

步骤 4:验证凭证提供程序

AgentCore Identity 会验证证书并在后台设置私有连接,因此新凭证提供程序会处于 CREATING 状态。请在几分钟后检查状态:

aws bedrock-agentcore-control get-oauth2-credential-provider \ --name keycloak-private-ca \ --query '{status: status, failureReason: failureReason}'

在控制台上,凭证提供程序的详细信息页面会在“根证书”下显示已配置的证书。当状态为 READY 时,您的代理即可向 IdP 请求令牌。如果状态为 CREATE_FAILED,failureReason 字段会说明原因。例如,“不允许叶子证书,只能提供 CA 证书”意味着您上传了服务器证书而非 CA 证书。如果看到“无法访问 S3 对象”或“Secrets Manager 找不到指定的密钥”,请检查 URI 或 ARN 是否正确,并确认您的身份有读取该对象或密钥的权限。如果提供程序已 READY 但令牌请求失败,请确认 IdP 的服务器证书是由配置的 CA 签发且其 SAN 与 IdP 主机名匹配。

监控并轮换 CA 证书

在验证凭证提供程序信任私有 CA 后,请监控 CA 证书的到期时间并在其到期前进行轮换,以防止令牌请求失败。当您的代理通过使用私有 CA 的凭证提供程序请求令牌时,AgentCore Identity 会将 EarliestCertificateDaysToExpiry 指标发布到 AWS/Bedrock-AgentCore 命名空间中的 Amazon CloudWatch。该指标报告距离 PEM 文件中最早的证书到期剩余的天数。它包含 ProviderName、ProviderArn 和 TokenVault 维度。创建警报时,请指定所有这三个维度。我们建议设置一个 CloudWatch 指标警报,在数值归零之前很长一段时间就发出通知,因为当 CA 证书到期时,发往 IdP 的令牌请求将停止工作。

注意:AgentCore Identity 仅在您创建或更新凭证提供程序时读取证书。如果您更改了密码或 S3 对象,请随后调用 UpdateOauth2CredentialProvider,以便 AgentCore Identity 读取新内容。在更新请求中包含 certificateConfigurations。如果将其遗漏,凭证提供程序将停止信任您的私有 CA。

一个 PEM 文件可以包含多个 CA 证书,AgentCore Identity 会信任其中每一个证书。您可以使用此功能轮换到新的 CA,同时将停机时间降至最低:

将当前和新的 CA 证书组合在一个文件中,例如使用 cat current-ca.pem new-ca.pem > rotation.pem。将该文件上传到您的密码或 S3 对象。

调用 UpdateOauth2CredentialProvider 并等待状态返回 READY。

用新 CA 签发的证书替换 IdP 的服务器证书。

在令牌请求成功后,上传仅包含新 CA 证书的文件,然后再次调用 UpdateOauth2CredentialProvider。

AgentCore Identity 不会检查证书吊销列表 (CRL) 或使用在线证书状态协议 (OCSP)。这意味着,如果未经授权的一方获取了 IdP 服务器证书的私钥,AgentCore Identity 将继续信任该证书。这种信任会持续到证书到期或您停止信任签发该证书的 CA 为止。要停止信任某个 CA,请将其从 PEM 文件中删除并更新凭证提供程序。

保护 CA 证书

CA 证书不包含私钥,根据设计它是公开的,因为您会将其交给每个必须信任您的 IdP 的客户端。您需要保护的是信任存储的数据完整性,即保存证书的密码或 S3 对象。如果有人替换了证书或向信任存储中添加了另一个 CA 证书,下一次更新可能会让能够重定向流量的未授权方冒充您的 IdP。

我们建议围绕写入权限而不是读取权限来设定范围。只将写入权限(例如 s3:PutObject 或 secretsmanager:PutSecretValue)授予运营 IdP 的团队或管道。将读取权限授予调用 CreateOauth2CredentialProvider 或 UpdateOauth2CredentialProvider 的主体。在这些操作期间,AgentCore Identity 使用调用者的 IAM 权限读取 CA 证书。以下针对中央身份账户 (444455556666) 的存储桶策略仅允许工作负载账户 (111122223333) 中管理凭证提供程序的角色读取 CA 证书。它还要求该角色必须属于您的 AWS Organizations 组织,并且拒绝 IdP 管理员角色以外的主体进行写入:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCredentialProviderAdminRead", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/AgentCoreCredentialProviderAdmin" }, "Action": "s3:GetObject", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/trust-anchors/*", "Condition": { "StringEquals": { "aws:PrincipalOrgID": "o-exampleorgid" } } }, { "Sid": "DenyWritesExceptIdpAdmin", "Effect": "Deny", "Principal": "*", "Action": ["s3:PutObject", "s3:DeleteObject"], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/trust-anchors/*", "Condition": { "ArnNotLike": { "aws:PrincipalArn": "arn:aws:iam::444455556666:role/IdpAdmin" } } } ] }

工作负载账户中的主体在其自己的 IAM 策略中也需要 s3:GetObject。对于必须位于同一账户中的 Secrets Manager,请在密码上使用基于资源的策略来限制对 IdP 管理员角色的写入。

由于密码在同一账户中,IAM 策略可以授予读取权限,因此资源策略只需要拒绝更改:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "DenyChangesExceptIdpAdmin", "Effect": "Deny", "Principal": "*", "Action": [ "secretsmanager:PutSecretValue", "secretsmanager:UpdateSecret", "secretsmanager:UpdateSecretVersionStage", "secretsmanager:RotateSecret", "secretsmanager:DeleteSecret", "secretsmanager:RestoreSecret", "secretsmanager:PutResourcePolicy", "secretsmanager:DeleteResourcePolicy" ], "Resource": "*", "Condition": { "ArnNotLike": { "aws:PrincipalArn": "arn:aws:iam::111122223333:role/IdpAdmin" } } } ] }

打开 S3 版本控制以恢复被覆盖的文件,并启用 AWS CloudTrail 数据事件以记录每一次更改。由于 CA 证书并非机密,SSE‑S3 加密已足够,并且可以避免客户托管密钥所需的跨账户 AWS KMS 权限。

将每个凭证提供程序的信任范围保持窄化。仅上传颁发 IdP 服务器证书的 CA,而不是整个组织的信任捆绑。如果您的 IdP 使用不同的 CA,请将每个 CA 证书分别存储在各自的 Secrets 或 S3 对象中,以便每个凭证提供程序仅信任其所需的 CA。

使用私有 CA 进行入站授权

您也可以使用私有 CA 进行入站授权。当 AgentCore Runtime 或 AgentCore Gateway(Amazon Bedrock AgentCore 的一项功能)验证由私有 IdP 签发的 JSON Web Token(JWT)时,它会从 JWKS 端点获取 IdP 的发现文档及其签名密钥。创建网关时,AgentCore Gateway 会验证发现 URL。如果缺少 CA 证书或其与 IdP 的证书链不匹配,网关状态会变为 FAILED,原因是“Failed to validate discovery url”。要信任该连接的私有 CA,请在 customJWTAuthorizer 配置中添加 certificateConfigurations,放在现有的 privateEndpoint 旁边:

"customJWTAuthorizer": { "discoveryUrl": "https://keycloak.example.local/realms/agents/.well-known/openid-configuration", "allowedClients": ["agentcore-client"], "privateEndpoint": { "managedVpcResource": { "vpcIdentifier": "vpc-0abc123def456", "subnetIds": ["subnet-0abc123", "subnet-0def456"], "securityGroupIds": ["sg-0abc123def456"], "endpointIpAddressType": "IPV4" } }, "certificateConfigurations": [ { "s3": { "uri": "s3://amzn-s3-demo-bucket/trust-anchors/keycloak-root-ca.pem", "bucketOwnerAccountId": "444455556666" } } ] }

清理

为避免持续产生费用,请删除您创建的资源:

在 AgentCore 控制台中删除凭证提供程序,或运行 aws bedrock-agentcore-control delete-oauth2-credential-provider --name keycloak-private-ca。

删除 Secrets Manager 中的密钥或 Amazon S3 中的对象。

从负载均衡器监听器中移除证书,然后在 ACM 中删除该证书。

在 AWS Private CA 控制台中禁用并随后删除私有 CA。AWS Private CA 会对每个 CA 收取月费,直至您将其删除。详情请参阅 AWS Private CA 定价。

结论

在本文中,我们展示了如何将 AgentCore 身份连接到使用您自有 CA 证书的自托管 IdP。您使用 AWS Private CA 颁发了服务器证书,将 CA 证书存储在 Secrets Manager 或 Amazon S3 中,并在凭证提供程序中引用它。您还了解了如何使用合并的 PEM 文件轮换 CA,以及如何限制谁可以更改代理信任的证书。

欲了解更多信息,请参阅《Amazon Bedrock AgentCore 开发者指南》中的“连接到私有身份提供商”。有关使用 Keycloak 的示例,请访问 GitHub 上的 Amazon Bedrock AgentCore 示例仓库。如有疑问或反馈,请在本文下方留言。

正文为 AI 译文。

参考来源

← 返回每日AI报告