多くのチームは、Keycloak や PingFederate などの ID プロバイダー (IdP) をプライベートネットワーク内でセルフホストしています。これらの IdP は通常、プライベート認証局 (CA) が発行した TLS サーバー証明書を提示します。Amazon Bedrock AgentCore Identity のプライベート CA サポートにより、エージェントは組織がすでに使用しているプライベート CA を信頼しながら、これらの IdP に接続できるようになりました。これは 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 をローテーションします。また、IdP チームのみが変更できるように CA 証明書を保護する方法も示します。AgentCore Identity は、エンタープライズ、サードパーティ、自己署名ルート CA など、あらゆるプライベート CA をサポートしていますが、このチュートリアルでは AWS Private CA と Keycloak を IdP として使用します。
ソリューションの概要
Keycloak IdP で保護された内部 wiki API を呼び出す必要があるエージェントを考えてみましょう。エージェントは、エージェントコードをホストする Amazon Bedrock AgentCore の機能である AgentCore Runtime 上で実行されます。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 がそれをエージェントに返します。
マシン間、オンビハーフオブ、ユーザー委任フローを使用するエージェントも、コードを変更せずにプライベート CA を使用できます。
前提条件
このチュートリアルを実行するには、以下が必要です。
- AgentCore コンソールにアクセスできる AWS アカウント。AgentCore Identity がプライベート IdP をサポートするサポート対象の AWS リージョンにあること。
- VPC 内で実行される、OpenID Connect (OIDC) 準拠のセルフホスト型 IdP。エージェント用に OAuth クライアントが登録されていること。ネットワーク要件(サブネット、セキュリティグループ、IdP ホスト名のプライベートホストゾーンなど)は「プライベート ID プロバイダーへの接続」で説明されています。
- 最新バージョンの AWS Command Line Interface (AWS CLI) と OpenSSL。
- 資格情報プロバイダーを作成する権限、および CA 証明書への読み取りアクセス。AgentCore Identity は CreateOauth2CredentialProvider を呼び出すプリンシパルの資格情報で証明書を読み取るため、そのプリンシパルにはシークレットに対する secretsmanager:GetSecretValue またはオブジェクトに対する s3:GetObject が必要です。シークレットまたはオブジェクトがカスタマーマネージド AWS Key Management Service (AWS KMS) キーで暗号化されている場合、プリンシパルにはそのキーに対する kms:Decrypt も必要です。
考慮事項
デプロイを計画する際は、以下に注意してください。
- プライベート IdP のみ:資格情報プロバイダーまたは認可者には、プライベート CA を使用するために privateEndpoint が必要です。そうでない場合、リクエストは「The private certificate authority feature can only be used with private IdP.」というメッセージで失敗します。
- PEM 形式の CA 証明書:ファイルは PEM エンコードされ、16 KB 以下である必要があります。有効期内のルート CA または中間 CA 証明書のみを含める必要があります。
- プロバイダーごとに 1 つの証明書ソース:各資格情報プロバイダーは 1 つのシークレットまたは 1 つの S3 オブジェクトを参照します。複数の CA を信頼するには、証明書を同じ PEM ファイルにまとめます。
- 保存場所:シークレットまたは S3 オブジェクトは、資格情報プロバイダーと同じ AWS リージョンにある必要があります。Secrets Manager シークレットは、資格情報プロバイダーと同じアカウントにもある必要があります。S3 オブジェクトは、bucketOwnerAccountId を指定し、バケットポリシーがアクセスを許可する場合、別のアカウントに置くことができます。
- リージョン:プライベート CA サポートは VPC Lattice に依存し、AgentCore Identity がプライベート IdP をサポートする AWS リージョンで利用できます。
チュートリアル
チュートリアルは 4 つのステップで構成されます。IdP がすでにエンタープライズ CA の証明書を提示している場合は、ステップ 2 に進んでください。
ステップ 1:IdP のサーバー証明書を発行する
まず、AWS Private CA でルート CA を作成します。手順については、「プライベート CA の作成」と「CA 証明書のインストール」を参照してください。短期証明書モードでは有効期間が 7 日以下の証明書が発行されるため、汎用モードを選択してください。CA を作成するときは、ACM が証明書を更新できるように承認し、ACM が IdP のサーバー証明書の有効期限が切れる前に更新できるようにします。
次に、サーバー証明書を要求します。AgentCore Identity は証明書が IdP ホスト名と一致することを確認するため、IdP のディスカバリドキュメントに表示される各ホスト名をサブジェクト代替名 (SAN) として含めます。ほとんどの Keycloak デプロイでは、ディスカバリ、JWKS、トークンエンドポイントが 1 つのホスト名を共有します。たとえば、ディスカバリ 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 は、IdP のサーバー証明書を検証するために CA 証明書を信頼する必要があります。サーバー証明書自体ではなく CA を信頼するため、サーバー証明書が更新されるたびに資格情報プロバイダーを更新する必要はありません。
AWS Private CA から CA 証明書を PEM 形式でエクスポートします。
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 はバケットが自分のアカウントにあることを期待します。クライアントシークレットをシェル履歴に残さないようにするには、Secrets Manager に保存したクライアントシークレットを参照できます。
ステップ 4:資格情報プロバイダーを検証する
AgentCore Identity はバックグラウンドで証明書を検証し、プライベート接続を設定するため、新しい資格情報プロバイダーは CREATING 状態で開始します。数分後に状態を確認します。
aws bedrock-agentcore-control get-oauth2-(記事はここで切れています)