View a markdown version of this page

Configurar a autoridade de certificação raiz para o Amazon Bedrock AgentCore Code Interpreter - Amazon Bedrock AgentCore
Como funcionaPré-requisitosArmazene seu certificado em AWS Secrets Manager Inicie uma sessão de intérprete de código com certificados personalizadosUsando vários certificadosConfigurar certificados no nível da ferramentaRequisitos e limites do certificadoSolução de problemas

Configurar a autoridade de certificação raiz para o Amazon Bedrock AgentCore Code Interpreter

Por padrão, as sessões do Amazon Bedrock AgentCore Code Interpreter confiam somente em autoridades de certificação reconhecidas publicamente. Se seus agentes precisarem acessar serviços ou recursos internos por meio de um TLS-intercepting proxy que usa certificados assinados por uma CA privada, você deverá fornecer seus certificados de CA raiz personalizados ao iniciar uma sessão.

O Amazon Bedrock AgentCore recupera o conteúdo do PEM-encoded certificado do AWS Secrets Manager usando suas credenciais de chamador, valida o X.509 formato e a expiração e instala os certificados no armazenamento confiável do sistema operacional da sessão. Isso permite que o interpretador de código estabeleça conexões HTTPS confiáveis com seus recursos internos.

Como funciona

A Autoridade de Certificação Raiz do Amazon Bedrock AgentCore Code Interpreter funciona da seguinte forma:

  1. Você fornece uma lista de localizações de certificados, cada uma apontando para um segredo no AWS Secrets Manager que contém um certificado CA PEM-encoded raiz.

  2. O Amazon Bedrock AgentCore usa suas credenciais de chamador para recuperar cada certificado do Secrets Manager. AWS

  3. Cada certificado é validado para o formato X.509 PEM correto e verificado para garantir que não tenha expirado e não seja usado antes da data de início da validade.

  4. Os certificados válidos são implantados no armazenamento confiável do sistema operacional da sessão, disponibilizando-os para os tempos de execução de código e para qualquer cliente de rede dentro do sandbox.

Os certificados configurados no nível da ferramenta (por meio deCreateCodeInterpreter) são combinados com quaisquer certificados fornecidos no horário de início da sessão. Isso permite que você defina certificados para toda a organização na ferramenta e adicione certificados específicos da sessão conforme necessário.

nota

A configuração do certificado é uma operação única por sessão. Depois que os certificados são instalados, eles não podem ser modificados durante a sessão.

Pré-requisitos

Antes de configurar os certificados de CA raiz, verifique se você tem o seguinte:

  • Concluiu os pré-requisitos gerais.

  • Seus certificados CA raiz são armazenados como AWS segredos no Secrets Manager. Cada segredo deve conter um PEM-encoded X.509 certificado válido

  • Permissões do IAM para ler os AWS segredos do certificado do Secrets Manager. Adicione as seguintes permissões à sua política do IAM:

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

Armazene seu certificado em AWS Secrets Manager 

Antes de usar um certificado CA raiz com o Amazon Bedrock AgentCore Code Interpreter, você deve armazená-lo como um segredo no AWS Secrets Manager. O valor secreto deve ser o conteúdo do PEM-encoded certificado.

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

Observe o ARN secreto da saída. Você usará esse ARN ao iniciar sessões com configuração de certificado.

Importante

O segredo deve conter um PEM-encoded X.509 certificado válido. O certificado não deve estar expirado e deve estar dentro do período de validade. O Amazon Bedrock AgentCore valida o formato e a validade do certificado antes de instalá-lo.

Inicie uma sessão de intérprete de código com certificados personalizados

Para iniciar uma sessão de intérprete de código que confia em seus certificados CA raiz personalizados, inclua o certificates parâmetro em sua StartCodeInterpreterSession solicitação.

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

Usando vários certificados

Você pode fornecer vários certificados de CA raiz em uma única sessão de intérprete de código. Isso é útil quando seu ambiente exige confiança para várias autoridades de certificação internas, como CAs separadas para diferentes serviços ou ambientes internos.

exemplo
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"
                }
            }
        }
    ]
)

Configurar certificados no nível da ferramenta

Você pode configurar certificados no nível da ferramenta ao criar um interpretador de código personalizado. Os certificados configurados no nível da ferramenta são aplicados automaticamente a cada sessão iniciada com essa ferramenta, além dos certificados fornecidos no horário de início da sessão.

Isso é útil para certificados de toda a organização, nos quais todas as sessões do interpretador de código devem confiar.

exemplo
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}")

Quando você inicia uma sessão com um interpretador de código que tem certificados configurados, os certificados em nível de ferramenta são combinados com qualquer certificado em nível de sessão. Tool-level os certificados são aplicados primeiro, seguidos pelos certificados em nível de sessão.

Requisitos e limites do certificado

Os certificados devem atender aos seguintes requisitos:

Requisito Detalhes

Formato

PEM-encoded X.509 certificado

Armazenamento

AWS Segredo do Secrets Manager (como um valor de string, não binário)

Validity

O certificado não deve estar expirado e deve estar dentro de seu período de validade (entre notBefore e notAfter datas)

Máximo de certificados por sessão

10 por sessão e 10 por ferramenta. Uma sessão pode ter até 20 certificados no total.

Formato ARN secreto

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

Tipo de localização

Somente o AWS Secrets Manager é suportado como um local de certificado

Solução de problemas

A tabela a seguir descreve erros comuns e suas resoluções ao configurar certificados CA raiz para o Amazon Bedrock AgentCore Code Interpreter.

Erro Causa Resolução

O segredo do certificado não foi encontrado no Secrets Manager

O ARN secreto não existe ou o segredo foi excluído.

Verifique se o ARN secreto está correto e se o segredo existe na região especificada.

Acesso negado ao certificado secreto no Secrets Manager

O chamador não tem secretsmanager:GetSecretValue permissão sobre o segredo.

Adicione a secretsmanager:GetSecretValue permissão à sua política do IAM para o ARN secreto especificado.

O conteúdo do certificado não é um PEM/X.509 formato válido

O valor secreto não é um PEM-encoded X.509 certificado válido.

Certifique-se de que o segredo contenha um certificado PEM formatado corretamente, começando com -----BEGIN CERTIFICATE----- e terminando com. -----END CERTIFICATE-----

O certificado expirou

A notAfter data do certificado está no passado.

Substitua o certificado expirado por um válido no AWS Secrets Manager e tente novamente.

O certificado ainda não é válido.

A notBefore data do certificado está no futuro.

Espere até que o período de validade do certificado comece ou use um certificado que seja válido no momento.

O número de certificados excede o máximo permitido

Mais de 10 certificados foram fornecidos no nível da sessão ou da ferramenta.

Reduza o número de certificados para 10 ou menos por sessão e 10 ou menos por ferramenta.

A localização do certificado é obrigatória

Uma entrada de certificado foi fornecida sem um local.

Certifique-se de que cada certificado na matriz inclua um location com uma secretsManager entrada contendo um válidosecretArn.

A configuração de certificados não está habilitada

O recurso de certificados não está habilitado para sua conta.

Entre em contato com o AWS Support para ativar o recurso de certificados em sua conta.