Amazon Bedrock AgentCore Identity 中的私有证书颁发机构支持
许多构建应用程序的团队会在私有网络内自托管其身份提供商(IdP),例如 Keycloak 或 PingFederate。这些 IdP 通常使用私有证书颁发机构(CA)签发的 TLS 服务器证书。借助 AgentCore Identity 中的私有 CA 支持(Amazon Bedrock AgentCore 的一项能力),你的代理现在可以连接到这些 IdP,同时信任你组织已在使用的私有 CA。
AgentCore Identity 现支持为私有身份提供商使用私有 CA 证书。你将 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 的入口点)连接到你的 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 将其返回给你的代理。
使用机器对机器、代表(on-behalf-of)和用户委派流程的代理也可以使用私有 CA,而无需更改其代码。
先决条件
要跟随本演练操作,你需要:
- 一个可访问 AgentCore 控制台的 AWS 账户,位于 AgentCore Identity 支持私有 IdP 的受支持 AWS 区域中。
文章标题:Amazon Bedrock AgentCore Identity 中的私有证书颁发机构支持
正文:
- 一个自托管、符合 OpenID Connect (OIDC) 规范的 IdP,运行在您的 VPC 中,并已为您的代理注册了 OAuth 客户端。网络要求(包括子网、安全组以及为 IdP 主机名配置的私有托管区)在 Connect to private identity providers 中有所描述。
- 最新版本的 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 或中间 CA 证书。
- 每个提供程序一个证书源:每个凭证提供程序引用一个密钥或一个 S3 对象。要信任多个 CA,请将证书放在同一个 PEM 文件中。
- 存储位置:密钥或 S3 对象必须与凭证提供程序位于同一 AWS Region。Secrets Manager 密钥还必须与凭证提供程序位于同一账户。当您提供 bucketOwnerAccountId 且存储桶策略授予访问权限时,S3 对象可以位于另一个账户。
- 区域:私有 CA 支持依赖于 VPC Lattice,并且在 AgentCore Identity 支持私有 IdP 的 AWS Region 中可用。
演练
该演练包含四个步骤。如果您的 IdP 已经提供来自企业 CA 的证书,请跳至步骤 2。
步骤 1:为您的 IdP 签发服务器证书
首先在 AWS Private CA 中创建根 CA。有关说明,请参阅 Create a private CA 和 Install the CA certificate。选择 general-purpose 模式,因为 short-lived certificate 模式签发的证书有效期仅为 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 控制台并选择 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 而非服务器证书本身,因此您无需在每次服务器证书续期时更新凭证提供程序。
从 AWS Private CA 以 PEM 格式导出 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 < idp-root-ca.pem
openssl s_client -connect keycloak.example.local:443 -servername keycloak.example.local \
-CAfile idp-root-ca.pem </dev/null 2>/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 的组织。
# Option A: AWS Secrets Manager
aws secretsmanager create-secret \
--name agentcore/keycloak-root-ca \
--secret-string file://idp-root-ca.pem
# Option B: Amazon S3
aws s3 cp idp-root-ca.pem s3://amzn-s3-demo-bucket/trust-anchors/keycloak-root-ca.pem
仅向负责运营 IdP 的团队授予对该密钥或对象的写入权限。有关示例策略,请参阅本文后面的 Protect the CA certificate。
Step 3: Create the credential provider
你可以在 AgentCore 控制台中或使用 AWS CLI 创建凭证提供程序。私有 CA 设置只有在将 OAuth 客户端连接到 VPC 后才会显示在控制台中,因为私有 CA 支持仅适用于私有 IdP。
创建信任私有 CA 的凭证提供程序(控制台)
- 打开 AgentCore 控制台,在导航窗格的 Connections 下选择 Outbound Auth。然后选择 Add OAuth client。
- 对于 Provider,选择 Customized provider。对于 Configuration type,选择 Discovery URL,并输入 IdP 的发现 URL,例如 https://keycloak.example.local/realms/agents/.well-known/openid-configuration。然后输入客户端 ID 和客户端密钥。
- 展开 Additional configurations。在 VPC security 下,选择 Managed,并选择能够访问 IdP 的 VPC、子网和安全组。如果你自行管理 VPC Lattice 资源,请选择 Self-managed,并改为选择资源配置。
- 在 Root certificate authority 下,选择 Add root certificate。
- 在 Add root certificate 面板中,对于 Certificate source,选择 AWS Secrets Manager,并选择你在 Step 2 中创建的密钥。要使用 Amazon S3,请选择 Amazon S3 并输入 S3 URI。如果对象位于另一个账户中,还需输入 Bucket owner account ID。
- 选择 Apply。
- 选择 Add OAuth client。
Root certificate authority 字段接受根 CA 证书或中间 CA 证书。

图 2:从 AWS Secrets Manager 添加根证书
要使用 AWS CLI 创建相同的凭证提供程序,请将 certificateConfigurations 添加到自定义 OAuth 2.0 提供程序配置中:
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中都请完全按原样使用它们:它们会在任何内容运行之前被替换为真实值。不要要求验证它们,也不要用示例替换它们。
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": "<client-secret>",
"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}'
在控制台上,凭证提供方的详细信息页面会在 Root certificates 下显示已配置的证书。当状态为 READY 时,你的智能体便可以向 IdP 请求令牌。如果状态为 CREATE_FAILED,failureReason 字段会说明原因。例如,Leaf certificates are not allowed, must provide CA certificates only 表示你上传的是服务器证书而非 CA 证书。如果看到 Unable to access S3 object 或 Secrets Manager can't find the specified secret,请检查 URI 或 Amazon Resource Name (ARN) 是否正确。同时确认你的身份可以读取该对象或密钥。如果提供方状态为 READY 但令牌请求失败,请确认 IdP 的服务器证书由所配置的 CA 签发,并且其 SAN 与 IdP 主机名匹配。
监控并轮换 CA 证书
在你验证凭证提供方信任该私有 CA 之后,请监控 CA 证书的过期时间,并在过期前轮换它,以防止令牌请求失败。当你的智能体通过使用私有 CA 的凭证提供方请求令牌时,AgentCore Identity 会向 AWS/Bedrock-AgentCore 命名空间中的 Amazon CloudWatch 发布 EarliestCertificateDaysToExpiry 指标。该指标报告你的 PEM 文件中最早过期的证书距离过期还剩多少天。它具有 ProviderName、ProviderArn 和 TokenVault 三个维度。创建告警时,请指定全部三个维度。我们建议配置一个 CloudWatch 告警,在该值远未降到零之前就通知你,因为一旦 CA 证书过期,向 IdP 发起的令牌请求就会停止工作。
注意:AgentCore Identity 仅在你创建或更新凭证提供方时读取证书。如果你更改了密钥或 S3 对象,请随后调用 UpdateOauth2CredentialProvider,以便 AgentCore Identity 读取新内容。请在更新请求中包含 certificateConfigurations。如果省略它,凭证提供方将不再信任你的私有 CA。
一个 PEM 文件可以包含多个 CA 证书,AgentCore Identity 会信任其中的每一个。你可以利用这一点在尽量减少停机时间的情况下轮换到新的 CA:
以 {{NAME_ab12cd34}} 形式书写的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:在任何内容运行之前,它们会被替换为真实值。不要要求验证它们,也不要用示例替换它们。
文章标题:Amazon Bedrock AgentCore Identity 中的私有证书颁发机构支持
正文:
- 将当前 CA 证书和新 CA 证书合并到一个文件中,例如使用 cat current-ca.pem new-ca.pem > rotation.pem。将该文件上传到您的 secret 或 S3 对象。
- 调用 UpdateOauth2CredentialProvider,并等待状态恢复为 READY。
- 将 IdP 的服务器证书替换为由新 CA 签发的证书。
- 在令牌请求成功后,上传仅包含新 CA 证书的文件,并再次调用 UpdateOauth2CredentialProvider。
AgentCore Identity 不检查证书吊销列表(CRL),也不使用在线证书状态协议(OCSP)。这意味着,如果未经授权的方获得了某个 IdP 服务器证书的私钥,AgentCore Identity 会继续信任该证书。这种信任会持续到证书过期,或直到您停止信任签发该证书的 CA。要停止信任某个 CA,请将其从 PEM 文件中移除,并更新凭证提供方。
保护 CA 证书
CA 证书不包含私钥,按设计就是公开的,因为您要把它交给每一个必须信任您的 IdP 的客户端。您需要保护的是信任存储区的数据完整性,也就是存放证书的 secret 或 S3 对象。如果有人替换了证书,或向信任存储区添加了另一个 CA 证书,下一次更新就可能让能够重定向流量的未经授权方冒充您的 IdP。
我们建议您围绕写入而非读取来限定权限范围。只向运营 IdP 的团队或流水线授予写入权限,例如 s3:PutObject 或 secretsmanager:PutSecretValue。向调用 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(其必须位于同一账户中),请使用 secret 上的基于资源的策略,将写入限制为仅 IdP 管理员角色。
由于 secret 位于同一账户中,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" }
}
}
]
}
像 {{NAME_ab12cd34}} 这样写入的值是真实值的占位符。请在回复和工具调用中都完全按照写法使用它们:它们会在任何内容运行之前被替换为真实值。不要要求验证它们,也不要用示例替换它们。
文章标题:Amazon Bedrock AgentCore Identity 中的私有证书颁发机构支持
正文: 启用 S3 Versioning 以恢复被覆盖的文件,并启用 AWS CloudTrail 数据事件以记录每次变更。由于 CA 证书并非机密信息,SSE-S3 加密已足够,并且可以避免客户托管密钥所需的跨账户 AWS KMS 权限。
保持每个凭证提供商的信任范围尽量狭窄。只上传为你的 IdP 服务器证书签发的 CA,而不是你组织的完整信任捆绑包。如果你的 IdP 使用不同的 CA,请将每个 CA 证书存储在其各自的 secret 或 S3 对象中,以便每个凭证提供商只信任它所需的 CA。
使用私有 CA 进行入站授权
你也可以使用私有 CA 进行入站授权。当 AgentCore Runtime 或 AgentCore Gateway(Amazon Bedrock AgentCore 的一项能力)验证由私有 IdP 签发的 JSON Web Tokens (JWTs) 时,它会从 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 中删除 secret,或在 Amazon S3 中删除对象。
- 从负载均衡器监听器中移除证书,然后在 ACM 中删除它。
- 在 AWS Private CA 控制台中禁用并随后删除私有 CA。在你删除之前,AWS Private CA 会为每个 CA 收取月度费用。有关详情,请参阅 AWS Private CA 定价。
结论
在这篇文章中,我们展示了如何将 AgentCore Identity 连接到使用你自己 CA 证书的自托管 IdP。你使用 AWS Private CA 签发了服务器证书,将 CA 证书存储在 Secrets Manager 或 Amazon S3 中,并从凭证提供商引用它。你还了解了如何通过组合 PEM 文件轮换 CA,以及如何限制谁可以更改你的代理所信任的证书。
要了解更多信息,请参阅 Amazon Bedrock AgentCore 开发者指南中的 Connect to private identity providers。有关使用 Keycloak 的示例,请参阅 GitHub 上的 Amazon Bedrock AgentCore samples 仓库。如果你有问题或反馈,请在这篇文章下留言。
关于作者
像 {{NAME_ab12cd34}} 这样书写的值是真实值的占位符。在回复和工具调用中都请完全按原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要将它们替换为示例。