Duas Maneiras de Autorizar uma Ferramenta de Agente: IAM ou OAuth no Amazon Bedrock AgentCore Gateway

Quando você expõe uma ferramenta para agentes, a decisão interessante não é a ferramenta. É quem tem permissão para chamá-la. O Amazon Bedrock AgentCore Gateway transforma essa decisão em um único campo — authorizerType — e o valor que você escolher determina se a ferramenta é uma capacidade privada para seus próprios agentes ou um serviço multi-inquilino que qualquer um pode acessar com um token.

Eu executo dois gateways na frente das ferramentas do AgentCore. Um é autorizado pelo IAM: meus agentes assinam cada solicitação com um perfil AWS, e não há nada na configuração que possa vazar. O outro é autorizado por um JWT de um provedor de identidade externo: os chamadores geram um token OAuth e o enviam como um cabeçalho bearer. A mesma primitiva de Gateway, modelos de confiança opostos. Este post é sobre como escolher entre eles — e a terceira opção que fica no meio.

O Gateway é um autorizador com uma ferramenta por trás dele

O AgentCore Gateway expõe ferramentas sobre o MCP. WebSearch, funções Lambda e outros conectores se conectam como alvos, e um agente os descobre com uma chamada padrão tools/list. Essa parte é uniforme. O que difere por gateway é o portão na frente dele.

Um Gateway tem exatamente um authorizerType, definido na criação, e aceita apenas dois valores:

• AWS_IAM — o chamador deve apresentar uma solicitação assinada com SigV4 de um principal AWS.
• CUSTOM_JWT — o chamador deve apresentar um JWT que o Gateway valida contra um provedor de identidade externo (emissor, audiência, expiração, escopos).

Tudo o mais — o protocolo MCP, o conector, o esquema da ferramenta — está a jusante dessa escolha. Então, "como eu conecto a pesquisa na web ao meu agente" é realmente "qual desses dois portões eu quero, e como o chamador passa por ele."

flowchart TD
    Q1{"O chamador está dentro da sua conta AWS?"}
    Q1 -->|sim| P1["Padrão 1: AWS_IAM + SigV4<br/>seus próprios agentes, Lambdas, tarefas"]
    Q1 -->|outra conta AWS| P2["Padrão 2: AWS_IAM + AssumeRole<br/>AWS-to-AWS B2B"]
    Q1 -->|sem identidade AWS| P3["Padrão 3: CUSTOM_JWT + OAuth<br/>parceiros, SaaS, multi-inquilino"]
    P1 --> G1["authorizerType = AWS_IAM"]
    P2 --> G1
    P3 --> G2["authorizerType = CUSTOM_JWT"]

Padrão 1 — IAM + SigV4: o chamador é você

Com AWS_IAM, a autorização se resume a uma única pergunta: o chamador possui credenciais AWS válidas para a conta que possui o gateway? SigV4 responde a isso em cada solicitação. Não há endpoint de token, nenhum segredo de cliente, nenhum loop de atualização.

O chamador resolve as credenciais a partir da cadeia padrão da AWS — variáveis de ambiente, depois um perfil nomeado, depois um papel de instância ou contêiner — e assina a solicitação. Em código, essa é a única parte que suporta carga:

import botocore.session, botocore.auth, botocore.awsrequest

creds = botocore.session.Session().get_credentials().get_frozen_credentials()
req = botocore.awsrequest.AWSRequest(method="POST", url=gateway_url, data=body, headers=headers)
botocore.auth.SigV4Auth(creds, "bedrock-agentcore", region).add_auth(req)

Note que o que get_credentials() não recebe: nenhuma chave de API, nenhum segredo, nenhum token. Na minha máquina, a configuração da ferramenta define um nome de perfil e uma região, e o botocore faz o resto. Não há nada nessa configuração que possa vazar, nada para rotacionar e nada para expirar.

A troca é o alcance. "Auth" aqui significa "tem uma identidade IAM na minha conta." Isso o torna perfeito para chamadores que já estão dentro do seu limite AWS — seu próprio laptop com um perfil, uma Lambda com um papel de execução, uma tarefa ECS com um papel de tarefa. Isso o torna a escolha errada no momento em que você deseja entregar a ferramenta a alguém que não está na sua conta, porque a única maneira de deixá-los entrar é dar a eles um principal IAM, que é uma concessão muito mais pesada do que "aqui está um token."

Padrão 2 — IAM + assunção de papel entre contas: o chamador é outra conta AWS

Se o chamador estiver na AWS, mas em uma conta diferente — um parceiro, uma conta de organização separada — você pode permanecer no mundo do IAM sem adicionar OAuth. Mantenha o gateway em AWS_IAM, e faça com que o chamador externo sts:AssumeRole em um papel na sua conta que tenha permissão para invocar o gateway. Eles assinam com as credenciais temporárias do papel assumido; o Gateway vê um principal válido da sua conta.

Isso estende a autenticação IAM através de uma fronteira de conta sem introduzir um provedor de identidade. Você gerencia uma política de confiança; eles gerenciam um salto de assunção de papel. Ainda sem tokens bearer, ainda sem distribuição de segredos.

O custo é que ambos os lados devem estar na AWS e confortáveis com a configuração de papéis entre contas. Isso não ajuda você a alcançar um chamador que não tem identidade AWS alguma — um backend SaaS, um serviço não AWS de um parceiro, um indivíduo ao qual você deseja conceder acesso entregando a ele uma credencial.

Padrão 3 — JWT + OAuth: o chamador é todos os outros

CUSTOM_JWT é a resposta multi-inquilino. O Gateway valida um JWT contra um provedor de identidade externo — verificando emissor, audiência, expiração e escopos — e o chamador obtém esse token da maneira que o IdP permitir. Para um chamador máquina-a-máquina, esse é o client_credentials grant: troque um ID de cliente e segredo por um token de acesso de curta duração, armazene em cache, atualize na expiração e envie como Authorization: Bearer <token>.

# token máquina-a-máquina, então cabeçalho bearer em cada chamada
token = post(f"https://{idp_domain}/oauth/token", json={