Validação de token JWT

Os tokens retornados pelo Identity se encontram no formato JWT assinado, ou seja, JWS.

Para validar os tokens JWT, sugerimos a utilização de alguma biblioteca open source, como as listadas nesta página, por ser um processo complexo e lidar com criptografia avançada.

As chaves de criptografia utilizadas no processo se encontram no JWKS do Identity na seguinte URL https://identity.iugu.com/.well-known/jwks.json.

Passo a passo de validação da assinatura dos tokens

1. Faça um request GET na URL https://identity.iugu.com/.well-known/jwks.json e salve este JSON
   Dica: guarde este valor cacheado em sua aplicação, sugerimos o valor de 12 hrs de TTL, pois estas chaves tendem a se manterem as mesmas por um período determinado de tempo, até que sejam rotacionadas
2. Utilize o JWKS e faça o processo de verificação da assinatura JWS
   Dica: utilize uma biblioteca open source de sua confiança, por ser um processo comum e bem documentado é fácil encontrar bibliotecas open source para as linguagens de programação mais utilizadas, explicar este processo está fora do escopo deste guia

Passo a passo de validação do access token

1. Faça o processo de validação de assinatura do token
2. Verifique se o valor da claim “typ” no header do token é “at+jwt” ou “application/at+jwt”, caso contrário ele deverá ser rejeitado
3. Verifique se o valor da claim “iss” é o https://identity.iugu.com, caso contrário ele deverá ser rejeitado
4. Verifique se a claim “aud” contém o valor do client id da sua aplicação
5. Verifique se a hora atual é anterior a hora presente na claim “exp”, essa validação garante que o token não está expirado, as aplicações podem adotar um “leeway” (margem de tolerância), caso queiram considerar problemas de desvio de relógio em sistemas distribuídos

Validações opcionais do access token

• Se sua aplicação solicitou um valor específico de nível de acesso através do parâmetro “acr_value”, é possível verificar se o token emitido possui o nível solicitado através da claim “acr”. Para saber mais a respeito de níveis de acesso dos tokens, acesse esta página.

Passo a passo de validação do id token

1. Faça o processo de validação de assinatura do token
2. Verifique se o valor da claim “iss” é o https://identity.iugu.com, caso contrário ele deverá ser rejeitado
3. Verifique se a claim “aud” contém o valor do client id da sua aplicação
4. Verifique se a claim “azp” contém o valor do client id da sua aplicação, caso seja a sua aplicação que tenha solicitado inicialmente este token
5. Verifique se a hora atual é anterior a hora presente na claim “exp”, essa validação garante que o token não está expirado, as aplicações podem adotar um “leeway” (margem de tolerância), caso queira considerar problemas de desvio de relógio em sistemas distribuídos

Validações opcionais do id token

• Se sua aplicação está solicitando algum valor específico de “max_age” (tempo de sessão do usuário no Identity), é possível utilizar a claim “auth_time” para verificar se o id token está dentro do valor máximo de sessão solicitado através “max_age”. Para saber mais a respeito de tempo de sessão do Identity, acesse esta página.