hiw3c 日报精选
AWS ML Blog RSS 全文

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

原文标题 · Private certificate authority support in Amazon Bedrock AgentCore Identity

Amazon Bedrock AgentCore身份现在支持私有证书颁发机构(CA),因此您的代理可以连接到使用私有CA的自托管身份提供商。本篇内容将介绍如何通过AWS私有CA颁发IdP证书、配置凭证提供器对其进行信任、轮换CA以及保护该证书。

来源:AWS ML Blog · aws.amazon.com

正文为英文,可一键机器翻译(仅首次需要等待)

Many teams that build applications self-host their identity provider (IdP), such as Keycloak or PingFederate, inside a private network. These IdPs usually present a TLS server certificate from a private certificate authority (CA). With private CA support in AgentCore Identity, a capability of Amazon Bedrock AgentCore, your agents can now connect to these IdPs while trusting the private CA that your organization already uses.

AgentCore Identity now supports private CA certificates for private identity providers. You store the PEM-encoded CA certificate in AWS Secrets Manager or Amazon Simple Storage Service (Amazon S3) and reference it from your credential provider. The CA certificate contains only the public certificate, not its private key. AgentCore Identity uses it to validate the server certificate presented by your IdP’s discovery, JSON Web Key Set (JWKS), and token endpoints. The CA certificate must be a root or intermediate CA certificate.

In this post, we show you how to issue an IdP certificate with AWS Private Certificate Authority. We then configure an AgentCore Identity credential provider to trust it and rotate the CA while minimizing downtime. We also show how to protect the CA certificate so that only your IdP team can change it. Although AgentCore Identity supports any private CA, including enterprise, third-party, and self-signed root CAs, the walkthrough in this post uses AWS Private CA and Keycloak as the IdP.

Solution overview

Consider an agent that needs to call an internal wiki API protected by your Keycloak IdP. The agent runs on AgentCore Runtime, a capability of Amazon Bedrock AgentCore, which hosts your agent code. To get an OAuth 2.0 access token from Keycloak, the agent uses an AgentCore Identity credential provider, which holds the IdP connection details and client credentials.

The following diagram shows this setup. Keycloak runs in your virtual private cloud (VPC) behind an internal Application Load Balancer. The load balancer presents an AWS Certificate Manager (ACM) private certificate signed by AWS Private CA. The CA certificate that AgentCore Identity trusts is stored in Secrets Manager or Amazon S3.

AgentCore Identity reaches the IdP privately through Amazon VPC Lattice, which connects to your VPC through a resource gateway, an entry point for VPC Lattice traffic into your VPC. VPC Lattice is required for private CA support. If you choose the managed option, AgentCore Identity creates and manages the VPC Lattice resources for you.

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

Figure 1: Connecting AgentCore Identity to a self-hosted IdP that uses a private CA

The flow works as follows:

  1. You store the CA certificate in Secrets Manager or Amazon S3.
  2. You create a credential provider that points to your IdP and to the CA certificate.
  3. AgentCore Identity reads the CA certificate and checks that it’s a valid CA certificate.
  4. Your agent requests an access token from AgentCore Identity.
  5. AgentCore Identity connects to the IdP through VPC Lattice and checks the load balancer certificate against your CA.
  6. The IdP issues the token and AgentCore Identity returns it to your agent.

Agents that use machine-to-machine, on-behalf-of, and user-delegated flows can also use the private CA without changing their code.

Prerequisites

To follow this walkthrough, you need:

  • An AWS account with access to the AgentCore console, in a supported AWS Region where AgentCore Identity supports private IdPs.
  • A self-hosted, OpenID Connect (OIDC) compliant IdP that runs in your VPC, with an OAuth client registered for your agent. The networking requirements, including subnets, security groups, and a private hosted zone for the IdP hostname, are described in Connect to private identity providers.
  • The latest version of the AWS Command Line Interface (AWS CLI) and OpenSSL.
  • Permission to create credential providers, plus read access to the CA certificate. AgentCore Identity reads the certificate with the credentials of the principal that calls CreateOauth2CredentialProvider, so that principal needs secretsmanager:GetSecretValue on the secret or s3:GetObject on the object. If the secret or object is encrypted with a customer managed AWS Key Management Service (AWS KMS) key, the principal also needs kms:Decrypt on that key.

Considerations

Keep the following in mind when you plan your deployment:

  • Private IdPs only: A credential provider or authorizer must have a privateEndpoint to use a private CA. Otherwise, the request fails with the message The private certificate authority feature can only be used with private IdP.
  • CA certificates in PEM format: The file must be PEM-encoded and no larger than 16 KB. It must contain only root or intermediate CA certificates that are within their validity period.
  • One certificate source per provider: Each credential provider references one secret or one S3 object. To trust more than one CA, put the certificates in the same PEM file.
  • Storage location: The secret or S3 object must be in the same AWS Region as the credential provider. Secrets Manager secrets must also be in the same account as the credential provider. S3 objects can be in another account when you provide bucketOwnerAccountId and the bucket policy grants access.
  • Regions: Private CA support depends on VPC Lattice and is available in the AWS Regions where AgentCore Identity supports private IdPs.

Walkthrough

The walkthrough has four steps. If your IdP already presents a certificate from your enterprise CA, skip to Step 2.

Step 1: Issue a server certificate for your IdP

Start by creating a root CA in AWS Private CA. For instructions, see Create a private CA and Install the CA certificate. Choose general-purpose mode, because short-lived certificate mode issues certificates that are valid for 7 days or less. When you create the CA, authorize ACM to renew certificates, so that ACM can renew the IdP’s server certificate before it expires.

Next, request the server certificate. AgentCore Identity checks that the certificate matches the IdP hostname, so include each hostname that appears in your IdP’s discovery document as a subject alternative name (SAN). In most Keycloak deployments, the discovery, JWKS, and token endpoints share one hostname. For example, if your discovery URL is https://keycloak.example.local/realms/agents/.well-known/openid-configuration, add keycloak.example.local as a SAN.

To request a private certificate for the IdP (console)

  1. Open the ACM console and choose Request.
  2. Choose Request a private certificate and then choose Next.
  3. For Certificate authority, choose the CA that you created.
  4. For Fully qualified domain name, enter the IdP hostname, for example keycloak.example.local.
  5. Choose Request.
  6. Attach the certificate to the HTTPS listener of the internal load balancer in front of your IdP. For instructions, see Update an HTTPS listener.

Step 2: Store the CA certificate

AgentCore Identity needs to trust the CA certificate to validate the IdP’s server certificate. Because it trusts the CA rather than the server certificate itself, you don’t need to update the credential provider each time the server certificate renews.

Export the CA certificate from AWS Private CA in PEM format:

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

Before you upload the file, check it against the requirements. The file must be PEM-encoded and meet size requirements, containing only CA certificates that are within their validity period. The following commands show the CA flag, expiry date, and file size. The last command confirms that the IdP’s certificate chains to this CA. Run it from a host that can reach the IdP. It returns Verify return code: 0 (ok) when the chain is valid.

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"

The output looks similar to the following:

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

Store the file in Secrets Manager or Amazon S3. A Secrets Manager secret must be a string secret in the same account as the credential provider. An S3 object can be in another account, which suits organizations that run the IdP in a central account.

# 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

Give write access to the secret or object only to the team that operates your IdP. For an example policy, see Protect the CA certificate later in this post.

Step 3: Create the credential provider

You can create the credential provider in the AgentCore console or with the AWS CLI. The private CA settings appear on the console only after you connect the OAuth client to a VPC, because private CA support applies only to private IdPs.

To create a credential provider that trusts your private CA (console)

  1. Open the AgentCore console and in the navigation pane under Connections, choose Outbound Auth. Then choose Add OAuth client.
  2. For Provider, choose Customized provider. For Configuration type, choose Discovery URL and enter your IdP’s discovery URL, for example https://keycloak.example.local/realms/agents/.well-known/openid-configuration. Then enter the client ID and client secret.
  3. Expand Additional configurations. Under VPC security, choose Managed and select the VPC, subnets, and security groups that can reach the IdP. If you manage your own VPC Lattice resources, choose Self-managed and select the resource configuration instead.
  4. Under Root certificate authority, choose Add root certificate.
  5. In the Add root certificate panel, for Certificate source, choose AWS Secrets Manager and select the secret that you created in Step 2. To use Amazon S3, choose Amazon S3 and enter the S3 URI. For an object in another account, also enter the Bucket owner account ID.
  6. Choose Apply.
  7. Choose Add OAuth client.

The Root certificate authority field accepts either a root or an intermediate CA certificate.

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

Figure 2: Adding a root certificate from AWS Secrets Manager

To create the same credential provider with the AWS CLI, add certificateConfigurations to the custom OAuth 2.0 provider configuration:

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"
          }
        }
      ]
    }
  }'

To use Amazon S3 instead, replace the certificateConfigurations entry with {"s3": {"uri": "s3://amzn-s3-demo-bucket/trust-anchors/keycloak-root-ca.pem", "bucketOwnerAccountId": "444455556666"}}. If you leave out bucketOwnerAccountId, AgentCore Identity expects the bucket to be in your own account. To keep the client secret out of your shell history, you can reference a client secret that you store in Secrets Manager.

Step 4: Verify the credential provider

AgentCore Identity validates the certificate and sets up private connectivity in the background, so a new credential provider starts in the CREATING status. Check the status after a few minutes:

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

On the console, the credential provider’s details page shows the configured certificate under Root certificates. When the status is READY, your agents can request tokens from the IdP. If the status is CREATE_FAILED, the failureReason field explains why. For example, Leaf certificates are not allowed, must provide CA certificates only means that you uploaded the server certificate instead of the CA certificate. If you see Unable to access S3 object or Secrets Manager can't find the specified secret, check that the URI or Amazon Resource Name (ARN) is correct. Also confirm that your identity can read the object or secret. If the provider is READY but token requests fail, confirm that the IdP’s server certificate was issued by the configured CA and has a SAN that matches the IdP hostname.

Monitor and rotate the CA certificate

After you verify that the credential provider trusts the private CA, monitor the CA certificate’s expiration and rotate it before it expires to prevent token request failures. AgentCore Identity publishes the EarliestCertificateDaysToExpiry metric to Amazon CloudWatch in the AWS/Bedrock-AgentCore namespace when your agents request tokens through a credential provider that uses a private CA. The metric reports the days remaining until the earliest certificate in your PEM file expires. It has ProviderName, ProviderArn, and TokenVault dimensions. When you create an alarm, specify all three. We recommend a CloudWatch alarm that notifies you well before the value reaches zero, because token requests to the IdP stop working when the CA certificate expires.

NOTE: AgentCore Identity reads the certificate only when you create or update the credential provider. If you change the secret or S3 object, call UpdateOauth2CredentialProvider a