Quando um JWT decodifica corretamente, não está expirado e pode até ter assinatura válida, mas a API ainda o rejeita, aud é um dos primeiros claims que comparo. Um audience mismatch geralmente significa que o token pode ser legítimo, porém foi emitido para outro destinatário.
Se já conheço a audiência que a API espera, uso o Depurador JWT para comparar diretamente esse valor com o aud do token.
O que aud deve responder
A RFC 7519 define aud como Audience. Eu leio como:
Para qual destinatário ou recurso este token foi emitido?
Pode existir uma audiência:
{
"aud": "api://orders"
}
ou várias:
{
"aud": ["api://orders", "api://reporting"]
}
Se a aplicação que faz a validação não é um destinatário permitido, o token deve ser rejeitado conforme a política do perfil.
Minha primeira comparação: esperado versus real
Começo com a comparação mais simples possível:
API espera: api://orders
Token aud: api://billing
Se os valores diferem, não torno a API “mais permissiva”. Volto ao fluxo de obtenção do token para descobrir por que o cliente pediu uma credencial para o recurso errado.
O Decodificador JWT mostra o valor bruto. Depois comparo exatamente com a configuração da API ou gateway.
Causa comum: recurso errado na solicitação
Um frontend pode autenticar o usuário corretamente e ainda solicitar token para o backend errado.
Exemplo: o login funciona, mas o authorization request pede acesso a Billing enquanto a aplicação depois chama Orders. O token pode estar assinado e ativo; simplesmente não foi emitido para o serviço que o recebeu.
Nesse caso, reviso resource, audience, scope ou identificador da API usado durante a obtenção do token. Não edito o JWT depois de emitido.
Causa comum: mistura de ambientes
Desenvolvimento, homologação e produção costumam ter audiences diferentes:
API espera: api://orders-prod
Token aud: api://orders-dev
Ao mesmo tempo, comparo iss. Se issuer e audience apontam para outro ambiente, a hipótese fica muito mais forte.
Verifico variáveis de ambiente, IDs da aplicação no provedor de identidade, configuração do gateway e parâmetros usados pelo cliente.
Causa comum: token do tipo errado
Outro padrão é enviar ID token para uma API que espera access token.
Em OpenID Connect, o ID token é voltado principalmente para o cliente. Sua audience pode ser o client ID. Já uma resource API normalmente espera um access token destinado àquele recurso.
Se aud parece ser o ID do frontend em vez do identificador da API, verifico qual variável foi colocada no Authorization: Bearer.
Não considero todos os tokens com formato JWT intercambiáveis.
Como trato múltiplas audiences
Como aud pode ser string ou array, a implementação precisa tratar ambas as formas corretamente.
Se o token contém:
{
"aud": ["api://orders", "api://reporting"]
}
um validador caseiro que espera apenas string pode gerar mismatch falso.
Também não transformo automaticamente os valores ou faço comparações parciais. A regra de comparação vem do perfil/provedor que está sendo usado.
Por que audience é uma fronteira de confiança
Um mesmo issuer confiável pode emitir tokens para várias APIs. Se cada API aceitasse qualquer token assinado pelo issuer sem validar audience, uma credencial destinada a um serviço poderia ser usada indevidamente em outro.
A RFC 8725 recomenda validar audience quando o mesmo emissor atende diferentes relying parties ou aplicações.
Por isso, para “resolver” mismatch, corrijo token acquisition ou configuração da API; não removo a checagem.
Por que não edito aud
Posso decodificar:
{"aud":"api://billing"}
alterar para:
{"aud":"api://orders"}
e reencodar o JSON. Mas os bytes assinados mudam e a assinatura original não deve mais verificar.
A correção legítima é obter do issuer um token para a audience correta ou corrigir a API se a configuração esperada estiver errada.
Audience, issuer e autorização são problemas diferentes
Mantenho as perguntas separadas:
iss: quem emitiu o token?aud: para quem ele foi emitido?- scopes/roles: o que o sujeito pode fazer?
Um token pode ter issuer correto e audience errada. Pode ter ambos corretos e ainda não possuir orders:write.
Depois que aud passa, continuo com scopes, roles e política específica do recurso. O guia de claims JWT ajuda a separar esses níveis.
Meu fluxo para audience mismatch
- Decodifico o JWT e leio
audexatamente como foi emitido. - Identifico qual API retornou o erro.
- Localizo a audience que essa API está configurada para aceitar.
- Comparo esperado e real.
- Verifico ambiente e tenant.
- Confirmo que o cliente enviou um access token destinado à API.
- Trato corretamente string e array em
aud. - Comparo
isscom o issuer confiável. - Verifico a assinatura com chaves ligadas a esse issuer.
- Corrijo aquisição ou configuração, sem editar o JWT.
Para um diagnóstico mais amplo, continuo no guia de JWT 401 Unauthorized.
A ideia central é: um token pode ser autêntico sem ser apropriado para todos os destinatários. aud existe justamente para representar essa fronteira.
