Uma credencial pode ser reconhecida pelo serviço e, mesmo assim, não ter permissão para a operação pedida. Separar a identidade da permissão ajuda a interpretar a recusa de uma integração e a escolher o que conferir.
Duas perguntas diferentes
A autenticação responde quem está chamando. A autorização responde o que essa identidade pode fazer. No HTTP, o código 401 indica a falta de uma credencial de autenticação válida, e o código 403 indica que o serviço recusou o atendimento. Uma credencial válida sem permissão para a operação é uma causa comum do 403, mas não a única.
Os mecanismos mais comuns
- Usuário e senha: identificam uma conta, que pode ser própria da integração. O programa pode trocá-los por um token em uma operação de login ou enviá-los em cada chamada.
- Basic: o esquema que envia o usuário e a senha no cabeçalho Authorization, codificados em Base64. A codificação não protege a senha, porque qualquer programa consegue decodificá-la, e por isso o Basic depende do HTTPS.
- API Key: uma chave entregue pelo fornecedor e apresentada em cada chamada, em um cabeçalho como X-API-Key ou da forma que o contrato definir. A chave pode identificar a aplicação, o projeto ou a conta e ter permissões e validade próprias.
- Token Bearer: um token apresentado no cabeçalho Authorization, depois da palavra Bearer. Quem apresenta um token aceito pode usá-lo dentro da validade e das permissões dele.
- Certificado do cliente: no mTLS, o programa apresenta um certificado na conexão e comprova que tem a chave privada correspondente.
- HMAC: um código calculado sobre a mensagem com um segredo compartilhado. O destinatário recalcula o código e confirma que a mensagem não foi alterada e que quem enviou conhece o segredo. O HMAC aparece com frequência na validação dos avisos enviados pelos fornecedores.
As credenciais também podem ir dentro de uma mensagem XML, em uma sessão ou em um cookie. O mecanismo de credencial não indica o estilo da API. Uma API Key, por exemplo, aparece em interfaces de estilos diferentes, assim como o usuário e a senha.
O OAuth 2.0 é um padrão de autorização por tokens. A aplicação obtém um token em um serviço de autorização e o apresenta nas chamadas, normalmente como token Bearer. O Client ID identifica a aplicação nesse processo, e o Client Secret é um dos segredos usados para autenticá-la.
O JWT, um formato de token
O JWT, sigla de JSON Web Token, é um formato de token que reúne informações chamadas claims, como sub, o sujeito, iat, o momento da emissão, e exp, o momento da expiração, quando presentes. A forma mais comum tem três partes separadas por pontos e costuma começar com eyJ, porque a primeira parte é um JSON codificado em Base64.
Decodificar o conteúdo de um JWT não verifica a assinatura nem a validade. Para aceitar o token, o serviço confere a assinatura, o emissor, o destinatário, a validade e as regras próprias. O Bearer é a forma de apresentar o token, e o JWT é um dos formatos possíveis. Um token Bearer pode ter outro formato, sem nenhum conteúdo legível.
Uma identidade, vários limites
Um token pode estar dentro da validade e servir a outro serviço, a outro ambiente, a outra loja ou a outro conjunto de operações. A assinatura correta não elimina essas restrições. No OAuth, o escopo indica as operações permitidas, e o destinatário indica o serviço que pode aceitar o token.
O certificado do cliente e o token também podem ser exigidos juntos, e comprovar a chave privada do certificado não substitui a autorização da operação. A comparação entre duas chamadas registra quais mecanismos a operação exige e quais foram usados, sem copiar os segredos.
No suporte
Diante do código 401, convém conferir a credencial, a validade, a operação e o ambiente. Diante do código 403, convém ler o motivo informado e conferir as permissões e as políticas. Os dados de rastreio ficam preservados e os segredos ficam mascarados, porque o código, sozinho, não indica qual informação está errada.
Para guardar
- A autenticação verifica a identidade, e a autorização define o que essa identidade pode fazer.
- O código 401 aponta a credencial, e o código 403 aponta a recusa do atendimento, muitas vezes por falta de permissão.
- O Basic apenas codifica a senha, sem protegê-la.
- O Bearer é a forma de apresentar um token, e o JWT é um dos formatos de token.
- Decodificar um JWT não valida a credencial.
O log mostra o cabeçalho Authorization com a palavra Bearer e um texto longo que começa com eyJ. Isso comprova que o token é um JWT válido?
Não. O Bearer indica a forma de apresentação, e o início eyJ é um indício de JWT. A validade depende da verificação feita pelo serviço, e o token completo não deve ser divulgado.
Uma conta reconhecida pelo serviço recebe o código 403 ao consultar pedidos. O que investigar?
As permissões dessa operação e as políticas indicadas na resposta, como o escopo, a loja e o ambiente. A autenticação pode estar correta, e o código 403 não mostra, sozinho, qual regra impediu o acesso.