许多团队在私有网络内自行托管身份提供商 (IdP),例如 Keycloak 或 PingFederate,这些 IdP 通常使用私有证书颁发机构 (CA) 签发的 TLS 服务器证书。Amazon Bedrock AgentCore Identity 现在支持私有 CA,使您的代理能够连接到这些 IdP,同时信任组织已使用的私有 CA。这项功能属于 Amazon Bedrock AgentCore 的一部分。
要使用此功能,您需要将 PEM 编码的 CA 证书存储在 AWS Secrets Manager 或 Amazon Simple Storage Service (Amazon S3) 中,并在凭证提供程序中引用它。该 CA 证书仅包含公有证书,不包含私钥。AgentCore Identity 使用它来验证 IdP 的发现、JSON Web Key Set (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。该代理运行在 AgentCore Runtime 上,这是 Amazon Bedrock AgentCore 的一项能力,用于托管代理代码。为了从 Keycloak 获取 OAuth 2.0 访问令牌,代理使用 AgentCore Identity 凭证提供程序,该程序保存了 IdP 连接详细信息和客户端凭证。
下图展示了此设置。Keycloak 在您的虚拟私有云 (VPC) 中运行,位于内部 Application Load Balancer 之后。负载均衡器提供由 AWS Private CA 签名的 AWS Certificate Manager (ACM) 私有证书。AgentCore Identity 信任的 CA 证书存储在 Secrets Manager 或 Amazon S3 中。
AgentCore Identity 通过 Amazon VPC Lattice 私有访问 IdP,VPC Lattice 通过资源网关(VPC Lattice 流量进入 VPC 的入口点)连接到您的 VPC。私有 CA 支持需要 VPC Lattice。如果选择托管选项,AgentCore Identity 会为您创建和管理 VPC Lattice 资源。
工作流程如下:
- 将 CA 证书存储在 Secrets Manager 或 Amazon S3 中。
- 创建指向 IdP 和 CA 证书的凭证提供程序。
- AgentCore Identity 读取 CA 证书并检查其是否为有效的 CA 证书。
- 您的代理向 AgentCore Identity 请求访问令牌。
- AgentCore Identity 通过 VPC Lattice 连接到 IdP,并根据您的 CA 检查负载均衡器证书。
- IdP 颁发令牌,AgentCore Identity 将其返回给代理。
使用机器对机器、代表 (on-behalf-of) 和用户委托流程的代理也可以使用私有 CA,而无需更改代码。
先决条件
要遵循本演练,您需要:
- 一个可以访问 AgentCore 控制台的 AWS 账户,位于 AgentCore Identity 支持私有 IdP 的受支持 AWS 区域。
- 一个在 VPC 中运行的自托管、兼容 OpenID Connect (OIDC) 的 IdP,并为您的代理注册了 OAuth 客户端。网络要求(包括子网、安全组和 IdP 主机名的私有托管区)在“连接到私有身份提供商”中描述。
- 最新版本的 AWS Command Line Interface (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 证书。
- 每个提供程序一个证书源:每个凭证提供程序引用一个密钥或一个 S3 对象。要信任多个 CA,请将证书放在同一个 PEM 文件中。
- 存储位置:密钥或 S3 对象必须与凭证提供程序位于同一 AWS 区域。Secrets Manager 密钥还必须与凭证提供程序位于同一账户。当您提供 bucketOwnerAccountId 且桶策略授予访问权限时,S3 对象可以位于另一个账户。
- 区域:私有 CA 支持依赖于 VPC Lattice,并在 AgentCore Identity 支持私有 IdP 的 AWS 区域中可用。
演练
演练包含四个步骤。如果您的 IdP 已经提供来自企业 CA 的证书,请跳到步骤 2。
步骤 1:为 IdP 签发服务器证书
首先在 AWS Private CA 中创建根 CA。有关说明,请参阅“创建私有 CA”和“安装 CA 证书”。选择通用模式,因为短期证书模式颁发的证书有效期不超过 7 天。创建 CA 时,授权 ACM 续订证书,以便 ACM 可以在 IdP 服务器证书过期前续订。
接下来,请求服务器证书。AgentCore Identity 会检查证书是否与 IdP 主机名匹配,因此请将 IdP 发现文档中出现的每个主机名作为主题备用名称 (SAN) 包含在内。在大多数 Keycloak 部署中,发现、JWKS 和令牌端点共享一个主机名。例如,如果您的发现 URL 是 https://keycloak.example.local/realms/agents/.well-known/openid-configuration,请添加 keycloak.example.local 作为 SAN。
要通过控制台为 IdP 请求私有证书:
- 打开 ACM 控制台并选择“请求”。
- 选择“请求私有证书”,然后选择“下一步”。
- 对于证书颁发机构,选择您创建的 CA。
- 对于完全限定域名,输入 IdP 主机名,例如 keycloak.example.local。
- 选择“请求”。
将证书附加到 IdP 前面的内部负载均衡器的 HTTPS 侦听器。有关说明,请参阅“更新 HTTPS 侦听器”。
步骤 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 密钥必须是字符串密钥,且与凭证提供程序位于同一账户。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 或中间 CA 证书。
要使用 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-(文章在此处截断)