Segurança de APIs para o CTO: identidade, gateway e tokens, sem confiar às cegas

Uma arquitetura de segurança de APIs frequente hoje tem três peças: um provedor de identidade que emite os tokens —Keycloak, Microsoft Entra ID, Okta ou outro—, um gateway que recebe todo o tráfego —APISIX, Kong, Apigee, Azure API Management ou outro— e o OAuth 2.0 como a linguagem com que as permissões são pedidas e apresentadas. É uma boa arquitetura. O problema aparece nas perguntas que ninguém escreveu ao desenhá-la: o serviço que fica atrás do gateway volta a verificar o token? O que acontece quando uma API chama outra? Se o usuário encerra a sessão, o token dele deixa de valer? Quanto tempo um token deve durar?

Este artigo responde a essas perguntas para quem precisa assinar a arquitetura: o CTO de um banco, de uma fintech, de uma seguradora, de uma rede de varejo ou de qualquer empresa regulada. Cada resposta vem com a condição que lhe cabe, porque em segurança quase nunca há um «sempre».

Três tipos de rota, três níveis de confiança

Antes de falar de tokens, convém classificar cada rota da API:

Uma API key identifica, mas não autoriza bem: não traz permissões finas, nem a quem se destina, nem vencimento padrão, nem delegação [1][2]. Serve para consumo simples, medição e cotas. Para uma integração entre empresas (B2B) com dados sensíveis, convém OAuth 2.0 com credenciais de cliente (client credentials): o sistema parceiro obtém por API um token de vida curta, com permissões restritas e destinado à API em questão [3][4]. Esse caminho se aplica quando o sistema age por conta própria ou sob um acordo prévio; não substitui o consentimento de uma pessoa. Se as API keys forem mantidas: uma por consumidor e por ambiente, guardadas como segredo, rotacionadas e nunca na URL, porque as URLs ficam registradas nos logs do gateway, dos proxies e das ferramentas de monitoramento, onde qualquer pessoa com acesso pode lê-las [2].

O serviço atrás do gateway deve verificar o token?

É a pergunta que gera mais discussões, e a resposta curta é: estar atrás do gateway não dá confiança por si só. Quem diz é o marco de confiança zero do NIST: a localização na rede não implica confiança, e a zona de confiança implícita deve ser a menor possível [5].

A resposta completa separa duas coisas que costumam ser confundidas:

• Validar o token (é autêntico, foi emitido pelo provedor, é para este serviço, continua vigente?).
• Autorizar a operação (esta pessoa ou este sistema pode ler esta conta, esta apólice, este pedido?).

A segunda, a autorização fina sobre o objeto, deve ser avaliada onde estejam disponíveis a regra de negócio e a relação com o objeto: normalmente no serviço ou em um componente de política integrado a ele. O gateway pode complementar com controles de granularidade grossa, mas não substitui essa regra. Uma permissão genérica como «ler pagamentos» não decide se alguém pode ler o pagamento de outro cliente. Esse erro tem nome e é o primeiro da lista de riscos de APIs da OWASP [6][7].

A primeira pode ser delegada ao gateway, mas somente se todas estas condições forem cumpridas [5][8][9]:

1. O serviço não é alcançável por nenhum outro caminho que não seja o gateway: nem de outra rede, nem de outro serviço vizinho, nem por uma rota administrativa.
2. O canal entre o gateway e o serviço é autenticado, por exemplo com TLS mútuo.
3. O gateway apaga qualquer cabeçalho de identidade que chegue de fora e coloca o próprio, assinado (por exemplo, um token interno) ou sobre um canal autenticado, de modo que o serviço possa verificar que vem do gateway.
4. A configuração de rotas é inventariada, testada e com falha fechada (fail-closed): uma rota sem regra não fica aberta.

Se uma condição não for cumprida, documente outro ponto de aplicação de política que valide de forma verificável a identidade de quem chama e o contexto; se não existir, o serviço deverá fazê-lo. E há casos em que convém que o valide mesmo que se cumpram as quatro: quando lida com dinheiro ou dados pessoais, quando decide com dados do token, ou quando atende vários clientes ou domínios.

Um detalhe de configuração que vale ouro: em alguns gateways, os plugins que validam API keys ou JWT repassam a credencial original ao serviço de trás a menos que se configure o contrário, e o de OpenID Connect, com bearer_only em false, não exige estritamente um bearer token [10][11]. São os valores documentados no APISIX 3.19 [provedor]; confirme a versão instalada e a configuração efetiva. Revisar esses valores padrão faz parte da arquitetura, não é um detalhe.

Quando uma API chama outra

Dentro da arquitetura, um serviço precisa chamar outro. Há cinco padrões frequentes, e cada uma serve para algo distinto [12][13][14]:

Uma regra que reduz o risco de reutilização indevida: cada serviço verifica se o token era destinado a ele. O campo que indica isso se chama audiência (aud), e se o serviço não está ali, o token é rejeitado [15][16]; para restringir o destino ao solicitá-lo, existem os indicadores de recurso (RFC 8707) [30]. Assim se evita o erro de «repassar às cegas» (token passthrough) e a consequência mais conhecida dele, o confused deputy: um serviço que, com um token alheio, faz algo que o usuário nunca autorizou. Por exemplo, um serviço de relatórios que recebe um token emitido para o serviço de pagamentos e, com ele, acaba podendo executar pagamentos.

Para a cadeia «A chama B em nome do usuário», o padrão recomendado é a troca de tokens: A troca o token que recebeu por um novo, destinado a B e com menos permissões [12]. No Keycloak, a função padrão V2 vem habilitada por padrão, mas o cliente solicitante deve ser confidencial e ter habilitado Standard token exchange; a troca padrão opera entre clientes do mesmo realm [17]. E o NIST propõe algo parecido para microsserviços: trocar o token externo na entrada por um interno de vida curta, e verificá-lo a cada salto [8].

Confiar no token ou perguntar ao provedor?

Há duas formas de saber se um token é bom:

Validar localmente não é só «a assinatura passou»: é preciso fixar o emissor esperado, aceitar somente os algoritmos previstos, verificar audiência, vencimento e permissões, e obter as chaves de um lugar confiável, porque o provedor as rotaciona: o serviço guarda em cache as chaves públicas e, quando chega um token assinado com uma chave que não conhece, volta a pedi-las em vez de rejeitá-lo ou de aceitá-lo às cegas [18][19]. E um custo que o CTO assina: com introspecção em cada requisição, o provedor de identidade fica no caminho crítico de todas as operações; se cai ou fica lento, cai ou fica lento tudo. E se o resultado de uma introspecção é guardado em cache, o tempo de cache não pode ser maior que a janela de revogação que o negócio aceita: um cache de cinco minutos contradiz uma promessa de revogação «imediata».

Encerrar a sessão não desativa os tokens já emitidos

Um efeito operacional relevante, que costuma surpreender um comitê de segurança: quando um usuário encerra a sessão, o access token que já tinha continua válido até vencer, para qualquer serviço que o valide localmente. Os mecanismos de encerramento de sessão do OpenID Connect terminam a sessão e avisam as aplicações, mas não invalidam os access tokens que já circulam [20][21]; a documentação do Keycloak alerta sobre isso de forma explícita [17].

Por isso a vigência é desenhada em camadas:

1. Access tokens curtos, para que a janela de exposição seja pequena.
2. Refresh tokens revogáveis, vinculados ao cliente e, em aplicações públicas, com rotação [3].
3. Introspecção nas operações em que o estado atual importa: transferências, mudanças de beneficiário, downloads em massa, ações administrativas.
4. Revogação (RFC 7009) quando o provedor a suporta [22].
5. Eventos de revogação entre sistemas (OpenID CAEP), que já são padrão final; o suporte nos provedores ainda é desigual [23].

Quanto tempo um token deve durar?

Não existe uma duração «padrão» em nenhuma norma. O OAuth deixa a vida do token a cargo do provedor [4]; o padrão de bearer tokens recomenda uma hora ou menos [24]; e o perfil de segurança do open banking (FAPI 2.0) pede tokens curtos sem fixar um número [25]. O que há são faixas iniciais de projeto —critério editorial, não uma norma—; ajuste-as à exposição, à janela de revogação, à reautenticação e à disponibilidade do provedor:

Os valores padrão do Keycloak [provedor] seguem essa linha. Foram verificados diretamente no código-fonte (ramo principal consultado em 6 de outubro de 2026), porque a documentação não os publica por completo [26]. São números do provedor e podem mudar entre versões:

No Keycloak, o refresh token de uma sessão normal vive o que a sessão permitir. Antes de confiar nesses números, convém revisar os da instalação em uso: os ajustes por cliente e as importações os alteram.

Quando é necessário o OpenID Connect?

• O OAuth 2.0 basta quando o que se protege é o acesso de uma aplicação ou de um sistema a uma API: integrações entre empresas, processos internos, permissões por escopo [4].
• O OpenID Connect convém quando a aplicação precisa de identidade autenticada interoperável, claims de autenticação ou acesso único (SSO) (também nível de autenticação, encerramento de sessão e reautenticação para ações sensíveis) [27]. O OAuth por si só não padroniza essa identidade: o OpenID Connect é a camada de identidade sobre o OAuth.
• Um erro frequente: usar o ID token do OpenID Connect para chamar uma API. O ID token é para a aplicação que iniciou a sessão; à API se envia o access token [27].

No open banking, a régua sobe

Se a API cai no mundo do open banking ou de dados financeiros, o perfil FAPI 2.0 (padrão final) sobe a régua: tokens vinculados a quem os usa —com TLS mútuo ou DPoP—, autenticação forte do cliente e parâmetros da requisição protegidos [25][28][29]. Não é obrigatório para todas as APIs nem é, por si só, uma obrigação mexicana: pode ser uma referência técnica útil para APIs de alto valor quando o marco aplicável, um contrato ou a política de risco o adotarem, e não substitui a avaliação das obrigações regulatórias aplicáveis.

Por onde começar

1. Classificar as rotas em públicas, com API key e com token, e verificar se cada uma está onde deve.
2. Decidir, serviço por serviço, quem valida o token, com as quatro condições acima por escrito.
3. Verificar a audiência em cada serviço e eliminar o repasse de tokens às cegas.
4. Revisar os valores padrão do provedor de identidade e do gateway.
5. Definir a janela de revogação por tipo de operação, e ajustar durações e introspecção a ela.

Quantas das rotas da empresa aguentariam hoje essa revisão? A primeira conversa de diagnóstico é sem custo: a empresa sai com o mapa das rotas por nível de confiança e as lacunas a tratar primeiro. Escreva para nós pelo WhatsApp.