Autenticação segura com OAuth no AgentCore Gateway para clientes MCP

O problema: assistentes de IA precisam de acesso seguro a ferramentas corporativas

No dia a dia de desenvolvimento moderno, assistentes de codificação baseados em IA — como o Kiro IDE — precisam se comunicar com ferramentas e serviços remotos para serem úteis. Mas essa comunicação levanta uma questão crítica de segurança: como garantir que apenas usuários e agentes autorizados consigam acessar essas ferramentas?

O Protocolo de Contexto de Modelo (MCP) é o padrão que define como esses assistentes se conectam a servidores de ferramentas. E para que essa conexão seja segura em ambientes corporativos, é preciso um mecanismo robusto de autenticação — de preferência integrado ao provedor de identidade (IdP) já utilizado pela organização, como Okta, Microsoft Entra ID ou Amazon Cognito.

A AWS publicou um guia técnico detalhando como implementar exatamente isso: o fluxo de código de autorização OAuth (Authorization Code Flow) como mecanismo de autenticação de entrada para servidores MCP hospedados no Amazon Bedrock AgentCore Gateway.

O que é o AgentCore Gateway e qual é o seu papel aqui

O Amazon Bedrock AgentCore é um serviço totalmente gerenciado para implantação, gerenciamento e escalonamento de agentes de IA em produção. Um de seus componentes principais, o AgentCore Gateway, funciona como ponto central de entrada para rotear e proteger as comunicações entre agentes e ferramentas.

Nessa arquitetura, o Gateway atua como um servidor de recurso OAuth: ele intercepta cada requisição do assistente de IA, valida o token de identidade apresentado e só então encaminha a requisição ao servidor MCP de destino. Esse processo é chamado de autenticação de entrada (inbound authentication).

Como o fluxo de autorização funciona na prática

O fluxo envolve cinco componentes principais trabalhando em conjunto:

Provedor de Identidade (IdP): gerencia a autenticação dos usuários e emite tokens. Pode ser Amazon Cognito, Okta, Auth0 ou qualquer IdP corporativo compatível com OpenID Connect (OIDC).
Usuário: a pessoa real que se autentica no IdP e cuja identidade é verificada em cada requisição.
Amazon Bedrock AgentCore Gateway: valida os tokens e encaminha as requisições autenticadas ao servidor MCP.
Assistente de codificação (Kiro IDE): atua como cliente OAuth, gerenciando todo o fluxo de autenticação automaticamente.
Servidor MCP: as ferramentas e serviços de back-end que o assistente precisa acessar.

Opcionalmente, um proxy OAuth para MCP pode ser utilizado para padronizar a interface entre o cliente, o IdP e o servidor MCP — especialmente útil quando há diferenças de implementação entre esses componentes.

O fluxo completo segue estas etapas:

O Kiro IDE tenta se conectar ao endpoint MCP do Gateway.
O Gateway detecta a ausência de token válido e responde com HTTP 401, apontando para o endpoint de metadados de recurso protegido (.well-known/oauth-protected-resource). Isso segue o padrão de Metadados de Recurso Protegido (PRM) da especificação MCP.
O cliente busca os metadados e obtém a URL de descoberta do IdP.
O Kiro IDE abre o navegador do sistema e redireciona o usuário para a página de login do IdP, com um desafio PKCE (Prova de Chave para Troca de Código).
O usuário se autentica e concede autorização.
O IdP redireciona o navegador para o callback local do cliente com um código de autorização.
O cliente troca esse código (junto com o verificador PKCE) por um token de acesso junto ao IdP.
A partir daí, o Kiro IDE inclui o token em todas as requisições ao Gateway, que valida assinatura, expiração, emissor e claims antes de encaminhar ao servidor MCP.

Implementação técnica passo a passo

Pré-requisitos

Conta AWS com o AgentCore Gateway implantado.
Um IdP com permissão para configurar um aplicativo (Amazon Cognito, Okta, Auth0 ou similar).
Proxy OAuth para MCP (mcp-remote).
Kiro IDE instalado localmente.
Conhecimento básico de fluxos OAuth 2.0.

Passo 1: Configurar o provedor de identidade

O primeiro passo é registrar um aplicativo OIDC no IdP da organização, configurando-o para suportar o fluxo de código de autorização com PKCE.

1.1 Criar o aplicativo OIDC — No console do IdP, crie uma nova integração de aplicativo OIDC/OAuth 2.0 com método de login OIDC e tipo de aplicação Web.

1.2 Habilitar os tipos de concessão — Ative Authorization Code e Refresh Token.

1.3 Definir as URIs de redirecionamento — Adicione o callback que o cliente utilizará:

http://localhost:PORT/callback

Substitua PORT pela porta que o cliente utiliza.

1.4 Configurar tempos de vida dos tokens — Recomendações do guia original:

Token de acesso: 1 hora
Token de atualização: 90 dias (ajustar conforme requisitos de segurança)
Token de ID: 1 hora

1.5 Salvar as configurações — Guarde o Client ID e a URL de descoberta do IdP (por exemplo: https://{yourIdPDomain}/oauth2/default/.well-known/openid-configuration). Importante: nenhum client secret é necessário, pois o PKCE foi projetado justamente para clientes públicos como aplicações desktop.

Passo 2: Configurar o AgentCore Gateway

2.1 Definir o modo de autenticação de entrada — Configure o Gateway para usar autenticação baseada em JWT (Token Web JSON) apontando para o endpoint de descoberta do IdP:

aws agentcore update-gateway \
  --gateway-id <your-gateway-id> \
  --inbound-auth-type JWT \
  --jwt-discovery-url "https://{yourIdPDomain}/oauth2/default/.well-known/openid-configuration" \
  --region <your-region>

2.2 Validação de claims personalizados — O Gateway valida tokens com base em claims padrão do OAuth 2.0 (iss, aud, exp, iat, client_id, scopes), mas também suporta validação de claims personalizados para acomodar diferentes implementações de IdP. Por exemplo, IdPs como o Okta podem usar cid em vez de client_id. Nesse caso, a configuração seria:

Custom claim: <claim-name> EQUALS <expected-value>

Consulte a documentação AgentCore Gateway: configuração de JWT para detalhes completos.

2.3 Como o Gateway valida tokens — Um ponto importante destacado no guia: o Gateway é agnóstico em relação à forma como o token foi obtido. Não importa se o token veio de um fluxo de credenciais de cliente ou de um fluxo de código de autorização — o que conta é que o token passe nas validações configuradas: assinatura, expiração, emissor e claims de audiência ou personalizados.

2.4 Verificar a configuração — Para confirmar que a autenticação está ativa, faça uma requisição sem token:

curl -i -X POST https://<your-gateway-url>/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

A resposta esperada é um HTTP 401 com o cabeçalho www-authenticate apontando para o endpoint de metadados:

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://<your-gateway-url>/.well-known/oauth-protected-resource"
{"jsonrpc":"2.0","id":0,"error":{"code":-32001,"message":"Missing Bearer token"}}

Passo 3: Instalar o proxy OAuth para MCP

Para padronizar a interface entre o Kiro IDE e o endpoint protegido do Gateway, o guia recomenda o uso do mcp-remote. Vale notar que essa ferramenta é descrita como uma prova de conceito funcional e deve ser tratada como experimental:

npm install -g mcp-remote

Passo 4: Configurar o Kiro IDE

Com o Gateway e o proxy configurados, o último passo é conectar o cliente ao endpoint do Gateway. O Kiro IDE gerencia o fluxo OAuth automaticamente ao receber um desafio 401.

Adicione a configuração no arquivo ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "gateway-tools": {
      "command": "mcp-remote",
      "args": [
        "https://<your-gateway-url>/mcp",
        "<PORT>",
        "--static-oauth-client-info",
        "{\"client_id\": \"<your-idp-client-id>\", \"redirect_uris\": [\"http://localhost:<PORT>/oauth/callback\"], \"scope\": \"openid profile email offline_access\"}"
      ]
    }
  }
}

Parâmetros da configuração:

command: usa o mcp-remote para se conectar a servidores MCP remotos.
Primeiro argumento: URL do Gateway com o caminho /mcp.
Segundo argumento: porta local para o callback OAuth (ex: 3334).
--static-oauth-client-info: JSON com client_id do IdP, redirect_uris (deve bater com a porta do segundo argumento) e scope com os escopos necessários.

Passo 5: Verificar o fluxo completo

Após reiniciar o cliente e tentar usar uma ferramenta do Gateway, o usuário é redirecionado ao navegador para login no IdP. Após autenticação bem-sucedida, a ferramenta é executada normalmente. Nos logs do Gateway, uma validação bem-sucedida aparece como:

[INFO] Token validated successfully for user: user@example.com
[INFO] Executing tool: list_files

Para um passo a passo completo usando o Okta como IdP, a AWS disponibilizou um repositório no GitHub com exemplos práticos.

Limpeza dos recursos

Para desfazer o ambiente criado durante os testes, o guia recomenda seguir a ordem inversa de criação:

Revogar tokens OAuth ativos — Consulte o endpoint de revogação do seu IdP. Em geral, a chamada segue este padrão:

curl -X POST "<your-idp-revocation-endpoint>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<your-refresh-token>&client_id=<your-client-id>"

Para limpar o cache local de tokens do mcp-remote (macOS/Linux):

rm -rf ~/.mcp-auth

Remover a configuração do Kiro IDE — Apague o bloco gateway-tools do arquivo ~/.kiro/settings/mcp.json.
Desinstalar o mcp-remote:
```
npm uninstall -g mcp-remote
```

Remover a configuração do Gateway — Duas opções:

# Opção A: remover apenas a autenticação de entrada
aws agentcore update-gateway \
  --gateway-id <your-gateway-id> \
  --inbound-auth-type NONE \
  --region <your-region>

# Opção B: deletar o Gateway completamente
aws agentcore delete-gateway \
  --gateway-id <your-gateway-id> \
  --region <your-region>

Remover o aplicativo OIDC do IdP — Acesse o console do IdP, navegue até o aplicativo criado (ex: “AgentCore Gateway client”), desative-o e exclua.

Principais conclusões

O guia publicado pela AWS demonstra uma arquitetura sólida para garantir acesso seguro e verificado por identidade a servidores MCP em ambientes corporativos. Os pontos mais relevantes:

O fluxo de código de autorização garante autenticação forte, com consentimento explícito do usuário e verificação de identidade.
O AgentCore Gateway atua como servidor de recurso OAuth, validando tokens antes de permitir qualquer execução de ferramentas.
O fluxo é transparente para o usuário final: a autenticação ocorre uma vez, e os tokens são renovados automaticamente.
A arquitetura escala para múltiplos clientes de IA e diferentes provedores de identidade.

Recursos adicionais

Fonte

Building a secure auth code flow setup using AgentCore Gateway with MCP clients (https://aws.amazon.com/blogs/machine-learning/building-a-secure-auth-code-flow-setup-using-agentcore-gateway-with-mcp-clients/)

Autenticação segura com OAuth no AgentCore Gateway para clientes MCP

O problema: assistentes de IA precisam de acesso seguro a ferramentas corporativas

O que é o AgentCore Gateway e qual é o seu papel aqui

Como o fluxo de autorização funciona na prática

Implementação técnica passo a passo

Pré-requisitos

Passo 1: Configurar o provedor de identidade

Passo 2: Configurar o AgentCore Gateway

Passo 3: Instalar o proxy OAuth para MCP

Passo 4: Configurar o Kiro IDE

Passo 5: Verificar o fluxo completo

Limpeza dos recursos

Principais conclusões

Recursos adicionais

Fonte

Comments

Leave a Reply Cancel reply

More posts

Permissões simplificadas para Amazon S3 Tables e views materializadas Iceberg chegam às regiões AWS GovCloud (US)

Amazon Bedrock AgentCore Runtime agora suporta shells interativos para acesso de terminal em sessões de agentes

Controle de acesso granular em aplicações B2C com Amazon Cognito e Amazon Verified Permissions

Amazon Cognito ganha novas capacidades com infraestrutura de nova geração