人工智能
Amazon Bedrock AgentCore Identity 中的私有证书颁发机构支持许多构建应用程序的团队会在私有网络内自行托管其身份提供商(IdP),例如 Keycloak 或 PingFederate。这些 IdP 通常会提供由私有证书颁发机构(CA)签发的 TLS 服务器证书。借助 AgentCore Identity(Amazon Bedrock AgentCore 的一项功能)中的私有 CA 支持,您的智能体现在可以连接到这些 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、第三方 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 Lattice 流量进入您的 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 随后将其返回给您的智能体。
使用机器到机器、代表用户和用户委托流程的智能体也可以使用私有 CA,而无须更改代码。
先决条件
要完成本演练,您需要:
- 一个 AWS 账户 ,能够访问 AgentCore 控制台,且该账户位于 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 证书或中间 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,而不是服务器证书本身,因此每次服务器证书续订时,您都无需更新凭证提供商。
从 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 的团队授予对该密钥或对象的写入权限。有关策略示例,请参阅本文后面的“保护 CA 证书”。
步骤 3:创建凭证提供商
您可以在 AgentCore 控制台中或使用 AWS CLI 创建凭证提供商。只有将 OAuth 客户端连接到 VPC 后,私有 CA 设置才会显示在控制台上,因为私有 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 证书。
图 2:从 AWS Secrets Manager 添加根证书
若要使用 AWS CLI 创建相同的凭证提供商,请将 certificateConfigurations 添加到自定义 OAuth 2.0 提供商配置中:
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}'
在控制台中,凭证提供商的详情页面会在 根证书下显示已配置的证书。当状态为 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 资源名称(ARN)是否正确。还要确认您的身份能够读取该对象或密钥。如果提供商处于 READY 状态,但令牌请求失败,请确认 IdP 的服务器证书由已配置的 CA 签发,并且包含与 IdP 主机名匹配的 SAN。
监控并轮换 CA 证书
确认凭证提供商信任私有 CA 后,请监控 CA 证书的到期时间,并在到期前进行轮换,以防令牌请求失败。当智能体通过使用私有 CA 的凭证提供商请求令牌时,AgentCore Identity 会将 EarliestCertificateDaysToExpiry 指标发布到 Amazon CloudWatch 的 AWS/Bedrock-AgentCore 命名空间中。该指标报告 PEM 文件中最早到期证书的剩余天数。它具有 ProviderName, ProviderArn和 TokenVault 维度。创建警报时,请指定全部三个维度。我们建议创建一个 CloudWatch 警报 ,以便在该值降至零之前提前通知您,因为 CA 证书到期后,向 IdP 发出的令牌请求将无法正常工作。
注意:AgentCore Identity 仅在您创建或更新凭证提供商时读取证书。如果您更改密钥或 S3 对象,请调用
UpdateOauth2CredentialProvider,以便 AgentCore Identity 读取新内容。在更新请求中包含certificateConfigurations。如果省略,凭证提供商将不再信任您的私有 CA。
一个 PEM 文件可以包含多个 CA 证书,AgentCore Identity 会信任其中每一个证书。您可以利用这一点轮换到新的 CA,同时尽量缩短停机时间:
- 将当前 CA 证书和新 CA 证书合并到一个文件中,例如使用
cat current-ca.pem new-ca.pem > rotation.pem。将该文件上传到您的密钥或 S3 对象。 - 调用
UpdateOauth2CredentialProvider,然后等待状态恢复为READY. - 将 IdP 的服务器证书替换为由新 CA 签发的证书。
- 令牌请求成功后,上传仅包含新 CA 证书的文件,并再次调用
UpdateOauth2CredentialProvider。
AgentCore Identity 不检查证书吊销列表(CRL),也不使用在线证书状态协议(OCSP)。这意味着,如果未经授权的一方获得了 IdP 服务器证书的私钥,AgentCore Identity 仍会继续信任该证书。这种信任将一直持续到证书到期,或您不再信任签发该证书的 CA。要停止信任某个 CA,请将其从 PEM 文件中移除并更新凭证提供商。
保护 CA 证书
CA 证书不包含私钥,并且本来就是公开的,因为您需要将其提供给所有必须信任您的 IdP 的客户端。真正需要保护的是信任存储的数据完整性,即保存证书的密钥或 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,请对密钥使用 基于资源的策略 ,将写入权限限制为 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 证书分别存储在独立的密钥或 S3 对象中,使每个凭证提供商仅信任其所需的 CA。
使用私有 CA 进行入站授权
您也可以使用私有 CA 进行入站授权。当 AgentCore Runtime 或 Amazon Bedrock AgentCore 的一项功能 AgentCore Gateway 验证由私有 IdP 签发的 JSON Web Token(JWT)时,它会从 JWKS 端点获取 IdP 的发现文档及其签名密钥。您创建网关时,AgentCore Gateway 会验证发现 URL。如果 CA 证书缺失或与 IdP 的证书链不匹配,网关状态将变为 FAILED ,原因为 Failed to validate discovery url。要使该连接信任私有 CA,请将 certificateConfigurations 添加到 customJWTAuthorizer 配置中,放在现有的 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,然后将其删除。在您删除 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 开发人员指南》中的“连接到私有身份提供商”。有关使用 Keycloak 的示例,请参阅 GitHub 上的 Amazon Bedrock AgentCore 示例存储库。如果您有任何问题或反馈,请在本文下方留言。
AI 热点