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 suporta os 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 aprender como configurá-la:

IAM-based autorização de entrada

IAM-based a autorização de entrada permite que você use as credenciais do 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 ligam para 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 a 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 JWT padrão ou criar um manualmente com um provedor de identidade compatível. Para saber mais sobre os diferentes métodos de configuração de um JWT, selecione um dos tópicos a seguir:

Configurar um JWT padrão

A AgentCore CLI permite criar facilmente uma configuração de autorização padrão usando o Amazon Cognito, que você pode usar ao criar um gateway. Quando você executaagentcore create, a CLI solicita que você configure a autorização de entrada e pode configurar automaticamente um grupo de usuários do Amazon Cognito para você.

agentcore create

Após a conclusão do comando, a AgentCore CLI fornece informações de autenticação e autorização:

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á CustomJWTAuthorizerConfigurationao criar um gateway, se forem aplicáveis ao seu caso de uso:

Você precisará desses valores para fazer o seguinte:

Publicidade de escopo em desafios de autenticação

Quando um cliente envia uma solicitação para 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 de OAuth necessários. Isso segue o formato de desafio do token RFC 6750 Bearer e permite que MCP-compliant os clientes descubram automaticamente os escopos necessários para a aquisição do token.

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 OAuth Protected Resource Metadata do gateway em/.well-known/oauth-protected-resource, que os clientes podem buscar para descobrir o servidor de autorização e os escopos compatíveis.

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 para permitir o acesso AgentCore à descoberta, ao token e aos endpoints JWKS privados do OIDC sem expô-los à Internet pública.

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

privateEndpointIsso se aplica ao domínio nodiscoveryUrl. Se seu provedor de identidade usa domínios diferentes para outros endpoints (por exemplo, o token ou o 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 Conecte-se a recursos privados em sua VPC usando o VPC Lattice. Para obter um guia abrangente que abrange cenários de IdP privado de entrada e saída, consulte Connect to private identity providers.

Autorização de entrada descarregada

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

AgentCore oferece dois tipos de descarga:

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

Authenticate-only autorização

Com a autorização somente de 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 própria. Qualquer diretor autenticado do IAM 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ítica 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 entrada do gateway 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: