Autenticação customizada para integração de ferramentas com o interceptor Lambda no AgentCore Gateway

O desafio: agentes modernos, ferramentas legadas

Ao implantar agentes de IA com o Amazon Bedrock AgentCore, as organizações contam com suporte nativo a mecanismos modernos de autenticação — OAuth 2.0, Gerenciamento de Identidade e Acesso da AWS (IAM) e autenticação por chave de API — diretamente pelo Amazon Bedrock AgentCore Gateway. O problema é que muitos ambientes corporativos ainda operam com mecanismos legados, como a Autenticação Básica HTTP (Basic Auth), definida na RFC 7617.

Para cobrir esse gap, a arquitetura extensível do AgentCore Gateway permite o uso de um interceptor Lambda de requisição — um código customizado executado toda vez que um agente chama uma ferramenta. A AWS publicou um guia detalhado mostrando como usar esse recurso para autenticar em APIs de ferramentas legadas com credenciais de sistema, sem expor essas credenciais ao agente.

Aviso importante antes de começar

A AWS é bastante direta no artigo: Basic Auth é uma tecnologia ultrapassada. Ela transmite credenciais como texto codificado em Base64 — o que não equivale à criptografia — e não deve ser adotada como estratégia de autenticação de longo prazo. A recomendação oficial é modernizar para OAuth 2.0, SAML, OpenID Connect ou IAM sempre que possível.

No entanto, a realidade de muitas empresas é que a modernização da autenticação e a adoção de IA agêntica são projetos com cronogramas independentes. A solução apresentada existe como medida temporária para quem precisa integrar agentes a sistemas legados agora, sem esperar a modernização completa. Se esse for o seu caso, a AWS recomenda consultar um Arquiteto de Soluções para avaliar os riscos antes de avançar.

Visão geral da solução

A solução utiliza um interceptor Lambda de requisição no AgentCore Gateway para recuperar credenciais de sistema e construir o cabeçalho Basic Auth necessário para a API da ferramenta de destino. O fluxo completo funciona assim:

• O agente de IA inicia uma chamada de ferramenta via Protocolo de Contexto de Modelo (MCP) para o gateway, acompanhada de um Token Web JSON (JWT) emitido por um provedor de identidade (IdP) configurado.
• A camada de autenticação de entrada do gateway valida o token contra o IdP especificado na configuração do autorizador de entrada.
• Após a autenticação de entrada ser bem-sucedida, o gateway invoca o interceptor Lambda de requisição, passando o payload original e os cabeçalhos da requisição — incluindo o JWT validado e seus atributos.
• O interceptor revalida o JWT como medida de defesa em profundidade e, em seguida, recupera a credencial da conta de serviço do AWS Secrets Manager.
• Com a credencial em mãos, o interceptor constrói um cabeçalho Basic Auth compatível e o adiciona à requisição de saída.
• O AgentCore Gateway encaminha a requisição ajustada para a ferramenta de destino, que autentica, processa e retorna a resposta ao agente.

Um ponto importante: como o Basic Auth transmite credenciais como texto Base64 (sem criptografia), é obrigatório garantir que toda comunicação com a API da ferramenta de destino ocorra sobre TLS. Além disso, alterações no código Lambda devem passar por revisão de duas pessoas como controle compensatório.

Gerenciamento do ciclo de vida da credencial

A credencial de sistema armazenada no Secrets Manager corresponde a uma conta de serviço no Active Directory (AD). O ciclo de vida exige uma semeadura manual única: um administrador cria a conta de serviço no AD e armazena a credencial inicial no Secrets Manager. Como o Secrets Manager não consegue ler uma senha diretamente do AD, esse passo inicial é necessário.

Como boa prática de segurança, a AWS recomenda acionar uma rotação imediata após a semeadura, para descartar a senha conhecida por humanos. A partir daí, o Secrets Manager automatiza o processo: gera periodicamente uma nova senha e atualiza tanto o Secrets Manager quanto o AD de forma simultânea, eliminando o gerenciamento manual de credenciais em ambos os sistemas.

Em tempo de execução, o interceptor Lambda recupera a credencial atual do Secrets Manager e a apresenta à ferramenta de destino, que a valida contra o AD. Para detalhes sobre como manter os dois repositórios sincronizados, a AWS disponibiliza documentação específica sobre rotação de credenciais do Active Directory armazenadas no AWS Secrets Manager.

Implementação passo a passo

O código de exemplo completo está disponível no repositório Implementando autenticação customizada para integração de ferramentas usando o Interceptor Lambda de Requisição. Os passos a seguir cobrem a configuração do interceptor e a lógica central de transformação de autenticação.

Passo 1: Vincular o interceptor Lambda de requisição ao AgentCore Gateway

O primeiro passo é configurar o AgentCore Gateway para invocar o interceptor Lambda antes de encaminhar a requisição à ferramenta de destino. Um detalhe crítico: é obrigatório habilitar a configuração passRequestHeaders. Sem ela, o interceptor não recebe o cabeçalho com o JWT de entrada, e todo o padrão de autenticação descrito aqui deixa de funcionar.

import boto3

bedrock_client = boto3.client('bedrock-agentcore-control', region_name='<your-region>')
# e.g., region_name='us-west-2'

bedrock_client.update_gateway(
    gatewayIdentifier='<your-gateway-id>',
    interceptorConfigurations=[
        {
            'interceptor': {
                'lambda': {
                    'arn': 'arn:aws:lambda:<region>:<account-id>:function:<YourInterceptorFunction>'
                }
            },
            'interceptionPoints': ['REQUEST'],
            'inputConfiguration': {
                'passRequestHeaders': True
            }
        }
    ]
)

Passo 2: Validar o JWT de entrada

O interceptor valida de forma independente a assinatura do JWT como medida de defesa em profundidade — protegendo contra cenários em que o interceptor poderia ser invocado por um caminho que contornasse a validação do gateway. Ele busca o Conjunto de Chaves Web JSON (JWKS) do provedor de identidade (com cache entre invocações Lambda aquecidas para evitar chamadas de rede repetidas), verifica a assinatura, expiração e emissor do token, e retorna os atributos decodificados.

import jwt
from jwt import PyJWKClient

COGNITO_ISSUER = f"https://cognito-idp.{COGNITO_REGION}.amazonaws.com/{YOUR_COGNITO_USER_POOL_ID}"

jwk_client = PyJWKClient(f"{COGNITO_ISSUER}/.well-known/jwks.json")

def validate_jwt(token):
    """Validate JWT signature and return decoded claims."""
    signing_key = jwk_client.get_signing_key_from_jwt(token)
    return jwt.decode(token, signing_key.key, algorithms=["RS256"], issuer=COGNITO_ISSUER)

Passo 3: Recuperar as credenciais de sistema do Secrets Manager

O interceptor recupera a credencial da conta de serviço do Secrets Manager. Essa credencial é usada para autenticar o agente de IA na ferramenta de destino. O segredo é criptografado com uma chave gerenciada pelo cliente no Serviço de Gerenciamento de Chaves da AWS (AWS KMS) e armazenado em cache na memória pelo tempo de vida (TTL) configurado, minimizando chamadas à API enquanto garante que credenciais rotacionadas sejam capturadas rapidamente.

import boto3

secrets_client = boto3.client('secretsmanager')

def get_system_credentials():
    """Retrieve the system service account credential from Secrets Manager."""
    response = secrets_client.get_secret_value(
        SecretId=os.environ['SYSTEM_CREDS_SECRET_NAME']
    )
    return json.loads(response['SecretString'])

Em relação às permissões do IAM: a função de execução do interceptor precisa de secretsmanager:GetSecretValue com escopo para o Nome de Recurso Amazon (ARN) específico do segredo, e kms:Decrypt com escopo para a chave KMS usada na criptografia. O princípio do menor privilégio deve ser aplicado restringindo o ARN do recurso em vez de usar curingas.

Vale destacar um ponto importante de segurança: o agente não tem acesso ao Secrets Manager. Apenas o interceptor Lambda de requisição — uma função determinística não influenciada pelo comportamento do modelo — recupera as credenciais. Esse isolamento é projetado para mitigar o risco de prompts adversariais instruindo o modelo a acessar ou exfiltrar segredos de autenticação, mesmo que o agente seja comprometido.

Passo 4: Construir o cabeçalho Basic Auth

Com o JWT validado e as credenciais em mãos, o interceptor constrói o cabeçalho Basic Auth para a ferramenta de destino.

def build_system_auth_header(headers):
    """Validate JWT and construct Basic Auth header with system credential."""
    auth_header = headers.get('Authorization', '')
    if not auth_header.startswith('Bearer '):
        return _error_response(401, "No Bearer token found in request.")

    # Validate JWT (defense-in-depth)
    claims = validate_jwt(auth_header[7:])
    if not claims:
        return _error_response(401, "JWT validation failed.")

    # Retrieve system credential from Secrets Manager
    creds = get_system_credentials()

    # Construct Basic Auth header (RFC 7617)
    basic_auth_encoded = base64.b64encode(
        f"{creds['username']}:{creds['password']}".encode()
    ).decode()
    headers['Authorization'] = f"Basic {basic_auth_encoded}"
    return headers

Conclusão

O interceptor Lambda de requisição no Amazon Bedrock AgentCore Gateway oferece uma ponte entre os padrões de autenticação suportados nativamente pelo gateway e os requisitos de autenticação de APIs de ferramentas legadas que ainda não migraram para padrões modernos. Como demonstrado, o interceptor valida o JWT de entrada, recupera credenciais de sistema do Secrets Manager e constrói o cabeçalho Basic Auth para a ferramenta de destino — sem modificar os esquemas das ferramentas nem a implementação do agente.

É importante reforçar: essa abordagem é um padrão de integração temporário, não uma arquitetura-alvo. Ela introduz uma credencial que precisa ser sincronizada entre o Secrets Manager e o repositório de identidades da ferramenta (como o Active Directory), adicionando sobrecarga operacional para rotação, detecção de desvios e gerenciamento de ciclo de vida. O caminho recomendado é modernizar a ferramenta de destino para aceitar OAuth 2.0, SAML ou OpenID Connect, eliminando completamente as credenciais armazenadas. Até que essa modernização seja concluída, o interceptor isola o tratamento de credenciais do runtime do agente, ajudando a garantir que o agente — um sistema não determinístico influenciado por prompts de usuários — não tenha acesso a segredos de autenticação.

Fonte

Implement custom authentication for tools integration using request Lambda interceptor in AgentCore Gateway (https://aws.amazon.com/blogs/security/implement-custom-authentication-for-tools-integration-using-request-lambda-interceptor-in-agentcore-gateway/)