As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configure a autorização de entrada para seu gateway

Antes de criar seu gateway, você deve configurar a autorização de entrada. A autorização de entrada valida os usuários que tentam acessar alvos por meio do seu AgentCore gateway. AgentCore oferece suporte aos seguintes tipos de autorização de entrada:

Se você não planeja usar a configuração de autorização padrão usando o Amazon Cognito, selecione o tópico que corresponde ao tipo de autorização que você planeja usar para saber como configurá-la:

IAM-based autorização de entrada

IAM-based a autorização de entrada permite que você use as credenciais IAM do chamador do gateway para autorização. Você pode usar essa opção se quiser criar uma identidade do IAM por meio da qual os usuários que chamam seu gateway possam ser autenticados.

Para configurar a autorização IAM-based de entrada

Política de exemplo

O exemplo a seguir mostra uma política que você pode anexar a uma identidade para permitir que ela invoque um gateway com o ID. my-gateway-12345

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowGatewayInvocation",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeGateway"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-12345"
      ]
    }
  ]
}

Recursos

Autorização de entrada baseada em JSON Web Token (JWT)

Um JSON Web Token (JWT) é um token seguro e compacto usado para autorização. Você pode criar um JWT com um provedor de identidade compatível. Depois de criar um JWT, você pode recuperá-lo e especificá-lo como a configuração de autorização ao criar o gateway.

Você pode usar a AgentCore CLI para configurar um gateway com um provedor de identidade JWT existente. Para saber mais sobre os métodos de configuração do JWT, selecione um dos seguintes tópicos:

Configurar um autorizador JWT

Crie um aplicativo e um cliente com um provedor de identidade compatível. Para ver um exemplo do Amazon Cognito, consulte Comece a usar o Amazon Cognito. Anote o URL de descoberta do OIDC e o ID do cliente.

Execute o seguinte comando em um diretório de AgentCore projeto:

agentcore add gateway \
  --name MyGateway \
  --protocol-type MCP \
  --authorizer-type CUSTOM_JWT \
  --discovery-url <OIDC_DISCOVERY_URL> \
  --allowed-clients <CLIENT_ID>

A AgentCore CLI consome a configuração OIDC existente; ela não cria os recursos do provedor de identidade. Para invocar o gateway, obtenha um token de acesso do seu provedor. Para o Amazon Cognito, consulte O endpoint emissor do token no Guia do desenvolvedor do Amazon Cognito.

Configurar um JWT manualmente

O Amazon Bedrock AgentCore oferece suporte a JWTs de todos os provedores de identidade. Você pode ver alguns exemplos em Configuração e configuração do provedor.

No processo de criação do JWT, anote os seguintes valores, que você preencherá CustomJWTAuthorizerConfiguration ao criar um gateway, se eles forem aplicáveis ao seu caso de uso:

Você precisará desses valores para fazer o seguinte:

Anúncio de escopo em desafios de autenticação

Quando um cliente envia uma solicitação a um JWT-authorized gateway sem um token de acesso válido, o gateway retorna uma resposta de erro com um WWW-Authenticate cabeçalho que anuncia os escopos OAuth necessários. Isso segue o formato de desafio de token RFC 6750 Bearer e permite que MCP-compliant os clientes descubram automaticamente os escopos necessários para a aquisição de tokens.

O gateway retorna as seguintes respostas, dependendo do erro:

O scope valor contém os escopos delimitados por espaço configurados como escopos permitidos no gateway. CustomJWTAuthorizerConfiguration O resource_metadata valor aponta para o documento de metadados de recursos protegidos OAuth do gateway em/.well-known/oauth-protected-resource, que os clientes podem buscar para descobrir o servidor de autorização e os escopos suportados.

Use um provedor de identidade privado (VPC-hosted)

AgentCore O Gateway oferece suporte JWT-based à autorização de entrada com provedores de identidade hospedados em sua VPC. Você pode configurar um privateEndpoint no customJWTAuthorizer AgentCore para permitir acessar seus endpoints privados de descoberta, token e JWKS do OIDC sem expô-los à Internet pública.

Seu diretor do IAM deve ter a iam:CreateServiceLinkedRole permissão deidentity-network.bedrock-agentcore.amazonaws.com, para que a AgentCore Identity possa criar a função AWSServiceRoleForBedrockAgentCoreIdentity vinculada ao serviço em seu nome, caso ela ainda não exista.

O privateEndpoint se aplica ao domínio nodiscoveryUrl. Se seu provedor de identidade usa domínios diferentes para outros endpoints (por exemplo, o token ou endpoint JWKS é resolvido para um domínio diferente do URL de descoberta), use para especificar uma configuração de endpoint privado separada privateEndpointOverrides para cada domínio adicional.

O exemplo a seguir cria um gateway com um provedor de identidade privado usando o Lattice gerenciado:

{
  "name": "my-private-idp-gateway",
  "protocolType": "MCP",
  "roleArn": "arn:aws:iam::123456789012:role/my-gateway-role",
  "authorizerType": "CUSTOM_JWT",
  "authorizerConfiguration": {
    "customJWTAuthorizer": {
      "allowedAudience": [
        "my-audience"
      ],
      "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration",
      "privateEndpoint": {
        "managedVpcResource": {
          "vpcIdentifier": "vpc-0abc123def456",
          "subnetIds": ["subnet-0abc123", "subnet-0def456"],
          "endpointIpAddressType": "IPV4",
          "securityGroupIds": ["sg-0abc123def"]
        }
      }
    }
  }
}

Se seu token ou endpoints JWKS usarem um domínio diferente do URL de descoberta, adicione uma privateEndpointOverrides entrada para cada domínio adicional. Atualmente, só privateEndpointOverrides é suportado com recursos autogerenciados do Lattice:

{
  ...
  "authorizerConfiguration": {
    "customJWTAuthorizer": {
      "allowedAudience": ["my-audience"],
      "discoveryUrl": "https://my-idp.internal.example.com/.well-known/openid-configuration",
      "privateEndpoint": {
        "selfManagedLatticeResource": {
          "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-abc123"
        }
      },
      "privateEndpointOverrides": [
        {
          "domain": "my-token-server.internal.example.com",
          "privateEndpoint": {
            "selfManagedLatticeResource": {
              "resourceConfigurationIdentifier": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-def456"
            }
          }
        }
      ]
    }
  }
}

Para Lattice autogerenciado, configurações entre contas e configurações avançadas, consulte Conectar-se a recursos privados em sua VPC usando o VPC Lattice. Para obter um guia abrangente sobre cenários de IdP privado de entrada e saída, consulte Conectar-se a provedores de identidade privados.

Autorização de entrada descarregada

Com a autorização de entrada descarregada, o gateway não toma nenhuma decisão de autorização por si só. Em vez disso, ele transfere a autorização para outro componente:

AgentCore oferece dois tipos de descarregamento:

Com qualquer um dos tipos, você decide onde a autorização é realmente aplicada:

Authenticate-only autorização

Com a autorização somente para autenticação (AUTHENTICATE_ONLY), o gateway verifica a assinatura Signature Version 4 (SigV4) do chamador para confirmar sua identidade, mas não toma nenhuma decisão de autorização por si só. Qualquer diretor de IAM autenticado pode invocar o gateway, independentemente de suas permissões, e a solicitação é encaminhada para o destino. A autorização é delegada ao serviço de destino downstream ou a um mecanismo de políticas conectado ao gateway.

Sem autorização

Você pode criar um gateway configurado sem autorização usandoauthorizerType=NONE. O gateway não executará nenhuma autorização na solicitação de gateway de entrada e a solicitação pode não ser autenticada.

Melhores práticas de segurança

Integre um tempo de execução existente sem alterar sua autenticação

Quando você combina um tipo de entrada descarregado com um tipo de autorização de saída correspondente que encaminha a identidade do chamador para o tempo de execução, a integração em um gateway pode ser tão simples quanto definir uma substituição de endpoint em seu cliente existente, sem necessidade de alterações de autenticação: