View a markdown version of this page

Configure a autorização de saída para seu gateway - Amazon Bedrock AgentCore
Configurar a autorização IAM-based de saída com uma função de serviço de gatewayConfigurar a autorização de saída com um cliente OAuthConfigurar a autorização de saída com uma chave de API

Configure a autorização de saída para seu gateway

A autorização de saída permite que os AgentCore gateways do Amazon Bedrock acessem com segurança os destinos do gateway em nome dos usuários que foram autenticados e autorizados durante a autorização de entrada.

AgentCore O Gateway suporta os seguintes tipos de autorização de saída:

  • Sem autorização (não recomendado) — Alguns tipos de destino oferecem a opção de ignorar a autorização de saída. Essa opção menos segura não é recomendada.

  • IAM-based autorização de saída — Use a função de serviço de gateway para autenticar o acesso ao destino do gateway com o AWS Signature Version 4 (Sig V4).

  • Credenciais do IAM do chamador — O gateway usa as credenciais do IAM do chamador para assinar solicitações para o destino. O gateway assume uma função em nome do chamador usando o Federated Access Service (FAS) e assina a solicitação de saída com a identidade do chamador. Isso é útil quando o serviço de destino precisa ser autorizado com base na identidade do chamador original, e não na função do serviço de gateway.

  • OAuth — Uma estrutura de autorização aberta que permite que um aplicativo cliente acesse recursos. Você pode usar o OAuth com um provedor de identidade incorporado ou com um personalizado. Para obter mais informações, consulte OAuth 2.0. Você pode usar os seguintes tipos de concessões de autorização do OAuth:

    • Concessão de credenciais do cliente — Machine-to-machine autenticação (também conhecida como OAuth de duas pernas). O aplicativo cliente acessa os recursos em nome do aplicativo, e não em nome do usuário.

    • Concessão de código de autorização — User-delegated acesso (também conhecido como OAuth de 3 pernas). O usuário dá consentimento para que o aplicativo cliente acesse recursos em nome do usuário.

    • Token exchange grant (On-behalf-of) — O gateway troca o token de acesso do usuário de entrada por um novo token de acesso com escopo definido que visa um recurso downstream. O token trocado carrega a identidade do usuário e a identidade do agente, permitindo que os serviços posteriores apliquem uma autorização refinada a cada salto sem acionar fluxos adicionais de consentimento. Para obter mais informações, consulte troca de On-behalf-of tokens.

  • Passagem de token — O gateway passa o token de autorização de entrada diretamente para o destino sem modificação. O serviço de destino é responsável por validar o token. Isso exige que o gateway use a autorização de AUTHENTICATE_ONLY entrada para que o token seja validado, mas preservado para encaminhamento.

  • Chave de API — Use o AgentCore serviço para gerar uma chave de API para autenticar o acesso ao destino do gateway.

O tipo de autorização de saída que você pode configurar depende do tipo de destino do gateway ao qual você autoriza o acesso:

Target type Sem autorização Função do serviço Gateway Credenciais do Caller IAM OAuth (credenciais do cliente) OAuth (código de autorização) OAuth (troca de tokens) Transferência de token Chave de API

Estágio da API Gateway

Sim

Sim

Não

Não

Não

Não

Não

Sim

Função do Lambda

Não

Sim

Não

Não

Não

Não

Não

Não

Servidor MCP

Sim

Sim

Não

Sim

Sim

Sim

Não

Sim

Esquema OpenAPI

Sim

Sim

Não

Sim

Sim

Sim

Não

Sim

Esquema Smithy

Não

Sim

Não

Sim

Não

Não

Não

Não

AgentCore Tempo de execução (HTTP)

Não

Sim

Sim

Sim

Não

Não

Sim

Não
nota

Se você usar um modelo de provedor de integração como destino, revise os tipos de autorização suportados para diferentes modelos em Built-in modelos de provedores de integração como destinos.

Antes de adicionar um destino ao seu gateway, você deve configurar a autorização para ele por meio de um dos métodos suportados.

nota

Você pode ignorar esse pré-requisito se planeja usar o console de AWS gerenciamento ou a AgentCore CLI para criar seu gateway. Se você usar qualquer uma dessas ferramentas, poderá criar AgentCore automaticamente uma função de serviço para você com as permissões necessárias para acessar o destino. Sempre que você adicionar um alvo, as permissões necessárias serão automaticamente anexadas à sua função de serviço.

Selecione um tópico para saber como configurar esse tipo de autorização:

Configurar a autorização IAM-based de saída com uma função de serviço de gateway

IAM-based a autorização de saída permite que você use as credenciais do IAM da função de serviço de gateway para autorizar com o AWS Signature Version 4 (Sig V4). Essa opção permite que o AgentCore serviço Amazon Bedrock se autentique nos destinos do gateway em nome dos chamadores do gateway.

Se você usar essa opção, verifique se a função do serviço de gateway tem bedrock-agentcore:InvokeGateway permissões. O gateway usa as credenciais da função de serviço para autenticação durante a invocação.

Configuração adicional para o servidor MCP e destinos OpenAPI

Ao usar a autorização de IAM-based saída com um servidor MCP ou destino OpenAPI, você deve fornecer configuração adicional para a assinatura SigV4. NocredentialProviderConfigurations, inclua um iamCredentialProvider com os seguintes campos:

  • service (obrigatório) — O nome do AWS serviço usado para assinatura SigV4. Por exemplo, bedrock-agentcore para servidores MCP hospedados no Amazon Bedrock AgentCore.

  • região (opcional) — A AWS região para assinatura SigV4. Se você não especificar uma região, o gateway usará sua própria região.

Para destinos Lambda, API Gateway e Smithy, não inclua o campo. iamCredentialProvider Esses tipos de destino suportam apenas a GATEWAY_IAM_ROLE configuração básica com credentialProviderType only. Para obter mais informações sobre como especificar a configuração do provedor de credenciais, consulte Autorização da função de serviço do AgentCore Gateway (IAM).

Práticas recomendadas de segurança para IAM-based autorização de saída

A função de execução do gateway é compartilhada entre todos os destinos configurados comGATEWAY_IAM_ROLE. Suas permissões são o limite superior do que qualquer chamador autorizado pode exercer por meio do gateway. Siga estas melhores práticas para limitar a exposição:

  • Defina o escopo da função de execução com permissões mínimas — conceda somente as permissões necessárias em todos os destinos configurados. Evite caracteres largos Action ou Resource curingas.

  • Use gateways separados para diferentes limites de confiança — Se os alvos tiverem níveis de sensibilidade diferentes ou atenderem a cargas de trabalho diferentes, implante-os em gateways separados com funções de execução distintas.

  • Use o mecanismo de política para restringir o acesso do chamador — Em gateways compartilhados, use o mecanismo de política para controlar quais chamadores podem invocar quais alvos, limitando o raio de explosão das permissões de qualquer chamador.

Configurar a autorização de saída com um cliente OAuth

Para configurar a autorização de saída com um cliente OAuth, você usa o serviço de AgentCore identidade e especifica as credenciais do cliente que você recebe ao criar um cliente em um provedor de identidade integrado (consulte Configuração e configuração do provedor ou um provedor de identidade personalizado).

Para configurar a autorização de saída com um cliente OAuth

  1. Registre seu aplicativo cliente com um provedor terceirizado compatível.

  2. Você receberá um ID do cliente, um segredo do cliente e possivelmente outros valores aos quais referenciará ao configurar a autorização de saída.

  3. Siga uma das etapas abaixo, dependendo de suas necessidades:

    • Para configurar a autorização de saída no console usando um provedor de identidade integrado, siga as etapas em Adicionar cliente OAuth usando o provedor incluído.

    • Para configurar a autorização de saída no console usando um provedor de identidade personalizado, siga as etapas em Adicionar cliente OAuth usando provedor personalizado.

    • Para configurar a autorização de saída usando a API, envie um CreateOauth2CredentialProvidercom um dos endpoints do plano de AgentCore controle. Para ver exemplos, consulte Exemplos para definir a autorização do cliente OAuth.

      nota

      A forma do objeto JSON para o qual o oauth2ProviderConfigInput campo é mapeado depende do provedor que você usa e deve ser congruente com o credentialProviderVendor valor especificado. Para ver exemplos de configurações diferentes para diferentes provedores de credenciais, consulte os exemplos de autorização de saída no provedor de credenciais de sua escolha em Configuração e configuração do provedor.

  4. Anote o ARN da credencial gerada credentialProviderArn (na API) e o ARN secreto do Secrets AWS Manager secretArn (na API). Você usará esses valores ao criar seu destino de gateway.

  5. (Se você estiver usando uma função de serviço de gateway personalizada) Anexe a seguinte política baseada em identidade à sua função de serviço de gateway:

    {
"Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "GetWorkloadAccessToken",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetWorkloadAccessToken",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
        ]
      },
      {
        "Sid": "GetResourceOauth2Token",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetResourceOauth2Token",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/oauth2credentialprovider/CredentialName"
        ]
      },
      {
        "Sid": "GetSecretValue",
        "Effect": "Allow",
        "Action": [
            "secretsmanager:GetSecretValue",
        ],
        "Resource": [
            "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
        ]
      }
    ]
}

    Substitua os valores dos seguintes campos:

    • Na GetWorkloadAccessToken declaração, substitua o GatewayName na Resource lista pelo nome do seu gateway.

    • Na GetResourceOauth2Token declaração, substitua o valor na Resource lista pelo ARN da credencial que você acabou de gerar.

    • Na GetSecretValue declaração, substitua o valor na Resource lista pelo ARN do AWS segredo retornado na resposta quando você gerou a credencial.

Exemplos para definir a autorização do cliente OAuth

Os exemplos a seguir mostram como definir a autorização por meio de um cliente OAuth para seu destino de gateway:

exemplo
AgentCore CLI

  1. Os comandos de credencial da AgentCore CLI devem ser executados dentro de um projeto agentcore existente. Se você ainda não tem um, crie um projeto primeiro comagentcore create.

    agentcore add credential \
  --name oauth-credential-provider \
  --type oauth \
  --discovery-url <DiscoveryUrl> \
  --client-id <ClientId> \
  --client-secret <ClientSecret>
agentcore deploy
AWS CLI

  1. aws bedrock-agentcore-control create-oauth2-credential-provider \
  --name oauth-credential-provider \
  --credential-provider-vendor CustomOAuth2 \
  --oauth2-provider-config-input '{
    "customOAuth2ProviderConfig": {
      "oauthDiscovery": {
        "discoveryUrl": "<DiscoveryUrl>"
      },
      "clientId": "<ClientId>",
      "clientSecret": "<ClientSecret>"
    }
  }'
Boto3

  1. import boto3

client = boto3.client("bedrock-agentcore-control")

client.create_oauth2_credential_provider(
  name="oauth-credential-provider",
  credentialProviderVendor="CustomOAuth2",
  oauth2ProviderConfigInput={
    "oauthDiscovery": {
      "discoveryUrl": "<DiscoveryUrl>"
    },
    "clientId": "<ClientId>",
    "clientSecret": "<ClientSecret>"
  }
)

Configurar a autorização de saída com uma chave de API

Para configurar a autorização de saída com uma chave de API, você usa o serviço de AgentCore identidade e especifica uma chave de API que você recebe de um provedor de identidade compatível.

Para configurar a autorização de saída com um cliente OAuth

  1. Registre seu aplicativo cliente com um provedor terceirizado compatível.

  2. Configure uma chave de API para o serviço do provedor. Anote os seguintes valores, que você especificará ao adicionar o destino do gateway:

    • Localização da credencial — se a chave da API deve ser colocada no cabeçalho ou como um parâmetro de consulta.

    • Prefixo da credencial — O prefixo da credencial (ex. Portador).

  3. Siga uma das etapas abaixo, dependendo de suas necessidades:

  4. Anote os seguintes valores, que você especificará ao adicionar o destino do gateway:

    • ARN do provedor de credenciais — Um nome de recurso da Amazon (ARN) gerado para o provedor de credenciais.

    • Nome — O nome que você deu à chave da API.

    • Secret ARN — Um ARN secreto do AWS Secrets Manager gerado para a chave da API.

  5. (Se você estiver usando uma função de serviço de gateway personalizada) Anexe a seguinte política baseada em identidade à sua função de serviço de gateway:

    {
"Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "GetWorkloadAccessToken",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetWorkloadAccessToken",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
        ]
      },
      {
        "Sid": "GetResourceApiKey",
        "Effect": "Allow",
        "Action": [
            "bedrock-agentcore:GetResourceApiKey",
        ],
        "Resource": [
            "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/apikeycredentialprovider/Name"
        ]
      },
      {
        "Sid": "GetSecretValue",
        "Effect": "Allow",
        "Action": [
            "secretsmanager:GetSecretValue",
        ],
        "Resource": [
            "arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
        ]
      }
    ]
}

    Substitua os valores dos seguintes campos:

    • Na GetWorkloadAccessToken declaração, substitua o GatewayName na Resource lista pelo nome do seu gateway.

    • Na GetResourceApiKey declaração, substitua o valor na Resource lista pelo ARN da credencial que você acabou de gerar.

    • Na GetSecretValue declaração, substitua o valor na Resource lista pelo ARN do AWS segredo retornado na resposta quando você gerou a credencial.

Exemplos de configuração de uma chave de API

Os exemplos a seguir mostram como definir uma chave de API para seu destino de gateway:

exemplo
AgentCore CLI

  1. Os comandos de credencial da AgentCore CLI devem ser executados dentro de um projeto agentcore existente. Se você ainda não tem um, crie um projeto primeiro comagentcore create.

    agentcore add credential \
  --name api-key-credential-provider \
  --type api-key \
  --api-key <API_KEY_VALUE>
agentcore deploy
AWS CLI

  1. aws bedrock-agentcore-control create-api-key-credential-provider \
  --name api-key-credential-provider \
  --api-key <API_KEY_VALUE>
Boto3

  1. import boto3

client = boto3.client("bedrock-agentcore-control")

client.create_api_key_credential_provider(
  name="api-key-credential-provider",
  apiKey="<API_KEY_VALUE>"
)