View a markdown version of this page

为 Amazon 基岩 AgentCore 代码解释器配置根证书颁发机构 - Amazon Bedrock AgentCore
工作原理先决条件将您的证书存储在 AWS Secrets Manager使用自定义证书启动代码解释器会话使用多个证书在工具级别配置证书证书要求和限制问题排查

为 Amazon 基岩 AgentCore 代码解释器配置根证书颁发机构

默认情况下，Amazon Bedrock AgentCore 代码解释器会话仅信任公开认可的证书颁发机构。如果您的代理需要访问使用私有 CA 签名证书的 TLS-intercepting 代理服务器背后的内部服务或资源，则必须在启动会话时提供您的自定义根 CA 证书。

Amazon Bedrock 使用您的调用者凭证从 S AWS ecrets Manager AgentCore 检索 PEM-encoded 证书内容，验证 X.509 格式和有效期，并将证书安装到会话的操作系统信任存储中。这使代码解释器能够与您的内部资源建立可信的 HTTPS 连接。

工作原理

Amazon Bedrock AgentCore 代码解释器的根证书颁发机构的工作原理如下：

  1. 您提供了证书位置列表，每个位置都指向 Secr AWS ets Manager 中包含 PEM-encoded 根 CA 证书的密钥。

  2. Amazon Bedrock AgentCore 使用你的来电者凭证从 S AWS ecrets Manager 中检索每个证书。

  3. 每份证书均经过验证以符合正确的 X.509 PEM 格式，并对其进行检查以确保其未过期且未在其有效期开始日期之前使用。

  4. 有效的证书将部署到会话的操作系统信任存储区，从而使代码执行运行时和沙箱中的任何网络客户端都可以使用这些证书。

在工具级别（通过CreateCodeInterpreter）配置的证书将与会话开始时提供的任何证书合并。这允许您在工具上设置组织范围的证书，并根据需要添加特定于会话的证书。

注意

证书配置是每个会话一次性操作。一旦安装了证书，就无法在该会话期间对其进行修改。

先决条件

在配置根 CA 证书之前，请确保您具备以下条件：

  • 已完成一般先决条件。

  • 您的根 CA 证书作为密钥存储在 Secrets Manager 中 AWS 。每个密钥必须包含有效的 PEM-encoded X.509 证书

  • 从 AWS Secrets Manager 读取证书密钥的 IAM 权限。将以下权限添加到您的 IAM 策略中：

    {
"Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SecretsManagerCertificateAccess",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:<Region>:<account-id>:secret:<secret-name>"
        }
    ]
}

将您的证书存储在 AWS Secrets Manager

在 Amazon Bedrock AgentCore 代码解释器中使用根 CA 证书之前，必须将其作为密钥存储在 Secr AWS ets Manager 中。密钥值必须是 PEM-encoded 证书内容。

例
AWS CLI

  1. aws secretsmanager create-secret \
  --name "my-corporate-root-ca" \
  --description "Corporate root CA certificate for AgentCore sessions" \
  --secret-string file://my-root-ca.pem \
  --region <region>
Boto3

  1. import boto3

client = boto3.client('secretsmanager', region_name='<region>')

# Read the PEM certificate file
with open('my-root-ca.pem', 'r') as f:
    cert_content = f.read()

response = client.create_secret(
    Name='my-corporate-root-ca',
    Description='Corporate root CA certificate for AgentCore sessions',
    SecretString=cert_content
)

print(f"Secret ARN: {response['ARN']}")

记下输出中的秘密 ARN。启动带有证书配置的会话时，您将使用此 ARN。

重要

密钥必须包含有效的 PEM-encoded X.509 证书。证书不得过期，并且必须在其有效期内。Amazon Bedrock 会在安装证书之前 AgentCore 验证证书格式和有效期。

使用自定义证书启动代码解释器会话

要启动信任您的自定义根 CA 证书的代码解释器会话，请在StartCodeInterpreterSession请求中包含certificates参数。

例
AWS CLI

  1. aws bedrock-agentcore start-code-interpreter-session \
  --code-interpreter-identifier "aws.codeinterpreter.v1" \
  --name "ci-session-with-custom-ca" \
  --certificates '[
    {
      "location": {
        "secretsManager": {
          "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:<secret-name>"
        }
      }
    }
  ]'
Boto3

  1. import boto3

client = boto3.client('bedrock-agentcore', region_name='<region>')

response = client.start_code_interpreter_session(
    codeInterpreterIdentifier="aws.codeinterpreter.v1",
    name="ci-session-with-custom-ca",
    certificates=[
        {
            "location": {
                "secretsManager": {
                    "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:<secret-name>"
                }
            }
        }
    ]
)

print(f"Session ID: {response['sessionId']}")
print(f"Status: {response['status']}")
API

  1. {
  "name": "ci-session-with-custom-ca",
  "certificates": [
    {
      "location": {
        "secretsManager": {
          "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:<secret-name>"
        }
      }
    }
  ]
}

使用多个证书

您可以在单个代码解释器会话中提供多个根 CA 证书。当您的环境要求信任多个内部证书颁发机构（例如不同的内部服务或环境的单独的 CA）时，这很有用。

例
AWS CLI

  1. aws bedrock-agentcore start-code-interpreter-session \
  --code-interpreter-identifier "aws.codeinterpreter.v1" \
  --name "ci-session-with-multiple-cas" \
  --certificates '[
    {
      "location": {
        "secretsManager": {
          "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:corporate-root-ca"
        }
      }
    },
    {
      "location": {
        "secretsManager": {
          "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:proxy-ca"
        }
      }
    }
  ]'
Boto3

  1. response = client.start_code_interpreter_session(
    codeInterpreterIdentifier="aws.codeinterpreter.v1",
    name="ci-session-with-multiple-cas",
    certificates=[
        {
            "location": {
                "secretsManager": {
                    "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:corporate-root-ca"
                }
            }
        },
        {
            "location": {
                "secretsManager": {
                    "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:proxy-ca"
                }
            }
        }
    ]
)

在工具级别配置证书

创建自定义代码解释器时，可以在工具级别配置证书。除了在会话开始时提供的任何证书外，在工具级别配置的证书还会自动应用于使用该工具启动的每个会话。

这对于所有代码解释器会话都应信任的组织范围的证书很有用。

例
Boto3

  1. response = client.create_code_interpreter(
    name="corporate-code-interpreter",
    description="Code interpreter with corporate CA trust",
    certificates=[
        {
            "location": {
                "secretsManager": {
                    "secretArn": "arn:aws:secretsmanager:<region>:<account-id>:secret:corporate-root-ca"
                }
            }
        }
    ]
)

ci_id = response['codeInterpreterIdentifier']
print(f"Code Interpreter ID: {ci_id}")

当您使用配置了证书的代码解释器启动会话时，工具级证书将与任何会话级别的证书组合在一起。 Tool-level 首先应用证书，然后应用会话级证书。

证书要求和限制

证书必须满足以下要求：

要求 说明

Format

PEM-encoded X.509 证书

仓储服务

AWS Secrets Manager 密钥（作为字符串值，而不是二进制值）

有效性

证书不得过期，并且必须在其有效期内（介于notBefore和notAfter日期之间）

每个会话的最大证书数量

每个会话 10 个，每个工具 10 个。一个会话总共最多可以有 20 个证书。

秘密 ARN 格式

arn:aws:secretsmanager:region:account-id:secret:secret-name

位置类型

仅支持 S AWS ecrets Manager 作为证书位置

问题排查

下表描述了为 Amazon Bedrock AgentCore 代码解释器配置根 CA 证书时的常见错误及其解决方法。

错误 原因 解决方案

在 Secrets Manager 中找不到证书密钥

密钥 ARN 不存在或密钥已被删除。

验证密钥 ARN 是否正确且该密钥存在于指定区域中。

对 Secrets Manager 中的证书密钥的访问被拒绝

来电者没有密钥的secretsmanager:GetSecretValue权限。

将指定机密 ARN 的secretsmanager:GetSecretValue权限添加到您的 IAM 策略中。

证书内容 PEM/X.509 格式无效

密钥值不是有效的 PEM-encoded X.509 证书。

确保密钥包含格式正确的 PEM 证书，开头-----BEGIN CERTIFICATE-----和结尾均为-----END CERTIFICATE-----。

证书已过期

证书的notAfter日期已过去。

在 S AWS ecrets Manager 中将过期的证书替换为有效的证书，然后重试。

证书尚未生效

证书的notBefore日期是将来的日期。

等到证书的有效期开始，或者使用当前有效的证书。

证书数量超过允许的最大值

在会话级别或工具级别提供了 10 多个证书。

将每个会话的证书数量减少到 10 个或更少，将每个工具的证书数量减少到 10 个或更少。

证书位置为必填项

提供的证书条目没有地点。

确保阵列中的每个证书都包含一个location，其secretsManager条目包含有效的证书secretArn。

证书配置未启用

您的账户未启用证书功能。

请联系 Su AWS pport 为您的账户启用证书功能。