跳到正文
AWS Machine Learning Blog· Aastha Paul·· 1 小时前AI 评分23

Amazon Bedrock AgentCore Identity 支持私有 CA 证书

Private certificate authority support in Amazon Bedrock AgentCore Identity

AI 导读

Amazon Bedrock AgentCore Identity 新增私有 CA 支持,智能体可连接使用私有 CA 签发 TLS 证书的自托管 IdP(如 Keycloak、PingFederate)。

正文 · AI 翻译

许多构建应用程序的团队会在私有网络内自托管其身份提供方(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,但本文的演练使用 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 资源。

AgentCore Identity reaches a Keycloak IdP through VPC Lattice and validates its server certificate against a private CA.

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

该流程如下:

  1. 你将 CA 证书存储在 Secrets Manager 或 Amazon S3 中。
  2. 你创建一个凭证提供方,指向你的 IdP 和该 CA 证书。
  3. AgentCore Identity 读取该 CA 证书并检查它是否为有效的 CA 证书。
  4. 你的代理向 AgentCore Identity 请求访问令牌。
  5. AgentCore Identity 通过 VPC Lattice 连接到 IdP,并依据你的 CA 检查负载均衡器证书。
  6. IdP 签发令牌,AgentCore Identity 将其返回给你的代理。

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

先决条件

要完成本演练,你需要:

  • 一个可访问 AgentCore 控制台的 AWS 账户,且位于 AgentCore Identity 支持私有 IdP 的受支持 AWS 区域。
  • 一个自托管、符合 OpenID Connect (OIDC) 规范且运行在您的 VPC 中的 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 或中间 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 请求私有证书(控制台)

  1. 打开 ACM 控制台并选择 Request。
  2. 选择 Request a private certificate,然后选择 Next。
  3. 对于 Certificate authority,选择您创建的 CA。
  4. 对于 Fully qualified domain name,输入 IdP 主机名,例如 keycloak.example.local。
  5. 选择 Request。
  6. 将证书附加到 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 的凭证提供程序(控制台)

  1. 打开 AgentCore 控制台,在导航窗格的 Connections 下选择 Outbound Auth。然后选择 Add OAuth client。
  2. 对于 Provider,选择 Customized provider。对于 Configuration type,选择 Discovery URL 并输入 IdP 的发现 URL,例如 https://keycloak.example.local/realms/agents/.well-known/openid-configuration。然后输入客户端 ID 和客户端密钥。
  3. 展开 Additional configurations。在 VPC security 下,选择 Managed,并选择能够访问 IdP 的 VPC、子网和安全组。如果你自行管理 VPC Lattice 资源,请选择 Self-managed,并改为选择资源配置。
  4. 在 Root certificate authority 下,选择 Add root certificate。
  5. 在 Add root certificate 面板中,对于 Certificate source,选择 AWS Secrets Manager,并选择你在步骤 2 中创建的密钥。要使用 Amazon S3,请选择 Amazon S3 并输入 S3 URI。对于位于其他账户中的对象,还需输入存储桶所有者账户 ID。
  6. 选择 Apply。
  7. 选择 Add OAuth client。

Root certificate authority 字段接受根 CA 证书或中间 CA 证书。

The AgentCore console Add root certificate panel with AWS Secrets Manager selected as the certificate source.

图 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}'

在控制台上,凭证提供程序的详情页会在 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 会将 EarliestCertificateDaysToExpiry 指标发布到 AWS/Bedrock-AgentCore 命名空间中的 Amazon CloudWatch。该指标报告你的 PEM 文件中最早到期的证书还剩多少天。它具有 ProviderName、ProviderArn 和 TokenVault 维度。创建告警时,请指定全部三个维度。我们建议使用一个 CloudWatch 告警,在该值远未达到零之前就通知你,因为当 CA 证书到期时,向 IdP 发起的令牌请求将停止工作。

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

一个 PEM 文件可以包含多个 CA 证书,AgentCore Identity 会信任其中的每一个。你可以利用这一点在最大限度减少停机时间的情况下轮换到新 CA:

  1. 将当前 CA 证书和新 CA 证书合并到一个文件中,例如使用 cat current-ca.pem new-ca.pem > rotation.pem。将该文件上传到你的密钥或 S3 对象。
  2. 调用 UpdateOauth2CredentialProvider 并等待状态恢复为 READY。
  3. 将 IdP 的服务器证书替换为由新 CA 签发的证书。
  4. 在令牌请求成功后,上传一个仅包含新 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 或 AgentCore Gateway(Amazon Bedrock AgentCore 的一项能力)验证由私有 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。在你删除之前,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 示例存储库。如果你有任何问题或反馈,请在这篇文章下发表评论。


关于作者

Aastha Paul

Aastha Paul

Aastha 是 AWS 的助理解决方案架构师。她专注于智能体安全和 Amazon Bedrock。

Swara Gandhi

Swara Gandhi

Swara 是 AWS 身份解决方案团队的高级解决方案架构师。她致力于构建安全且可扩展的端到端身份解决方案。她对身份、安全和云领域的一切充满热情。

来源:AWS Machine Learning Blog · aws.amazon.com