Como posso decodificar e verificar a assinatura de um JSON Web Token do Amazon Cognito?

Breve descrição

Quando os clientes usam um grupo de usuários para se autenticar em sua aplicação, o Cognito envia um JSON Web Token (JWT) para você decodificar, ler e modificar. Para obter detalhes do usuário do Cognito de um JWT, decodifique o token e verifique a assinatura.

Importante: Antes de conceder acesso aos seus recursos, você deve verificar a assinatura.

Resolução

Verifique se o Cognito emitiu JWTs

Use o código a seguir em JavaScript:

import { CognitoJwtVerifier } from "aws-jwt-verify";

// Verifier that expects valid access tokens:
const verifier = CognitoJwtVerifier.create({
  userPoolId: "user_pool_id",
  tokenUse: "access",
  clientId: "client_id",
});

try {
  const payload = await verifier.verify(
    "eyJraWQeyJhdF9oYXNoIjoidk..." // the JWT as string
  );
  console.log("Token is valid. Payload:", payload);
} catch {
  console.log("Token not valid!");
}

Observação: Substitua user_pool_id pelo ID do grupo de usuários e client_id pelo ID do cliente da aplicação. Para o token de ID, atualize o campo tokenUse para “id”. Para obter uma lista dos parâmetros disponíveis, consulte aws-jwt-verify no site do GitHub.

Se você usa outra linguagem de programação, consulte as bibliotecas jwt.io no site do JWT ou as bibliotecas do OpenID Connect no site da OpenID. Para ver um exemplo de código, consulte Decodificar e verificar os tokens JWT do Amazon Cognito no site do GitHub.

O Cognito retorna até três tokens: o token de ID, o token de acesso e o token de atualização.Se você usar APIs REST, AWS Amplify ou AWS SDKs para autenticar um usuário, receberá todos os três tokens.

Para a interface de usuário hospedada pelo Cognito, o token que você recebe depende do tipo de concessão de autorização que você usa. Se você usar a concessão implícita, receberá somente o acesso e o token de ID.A concessão do código de autorização retorna tokens de acesso, ID e atualização. A concessão de credenciais do cliente retorna somente o token de acesso.

Os tokens de acesso e ID incluem um cabeçalho, um payload e uma assinatura. O cliente não consegue decodificar nem verificar o token de atualização.

Veja a seguir um exemplo de cabeçalho do token de ID. O cabeçalho contém a ID da chave (“kid”) e o algoritmo (“alg”) usado para assinar o token. O algoritmo RS256 é uma assinatura RSA com SHA-256:

{
  "kid": "key_id_example=",
  "alg": "RS256"
}

Veja a seguir um exemplo de um payload que contém informações sobre o usuário e os registros de data e hora da criação e expiração do token:

{
  "sub": "aaaaaaaa-bbbb-cccc-dddd-example",
  "aud": "audience_example",
  "email_verified": true,
  "token_use": "id",
  "auth_time": 1500009400,
  "iss": "https://cognito-idp.ap-southeast-2.amazonaws.com/ap-southeast-2_example",
  "cognito:username": "anaya",
  "exp": 1500013000,
  "given_name": "Anaya",
  "iat": 1500009400,
  "email": "anaya@example.com"
}

A assinatura é uma combinação com hash e criptografada do cabeçalho e do payload.

O Cognito gera dois pares de chaves RSA para cada grupo de usuários. A chave privada de cada par é usada para assinar criptograficamente o token de ID ou o token de acesso. Você pode encontrar as chaves públicas em um endereço no seguinte local:

https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/jwks.json

Observação: Substitua a região pela região da AWS onde está seu grupo de usuários e userPoolID pelo ID do grupo de usuários.

O arquivo JSON (jwks.json) está estruturado no seguinte formato:

{    "keys": [{
        "alg": "RS256",
        "e": "AQAB",
        "kid": "abcdefghijklmnopqrsexample=",
        "kty": "RSA",
        "n": "lsjhglskjhgslkjgh43lj5h34lkjh34lkjht3example",
        "use": "sig"
    }, {
        "alg":
        "RS256",
        "e": "AQAB",
        "kid": "fgjhlkhjlkhexample=",
        "kty": "RSA",
        "n": "sgjhlk6jp98ugp98up34hpexample",
        "use": "sig"
    }]
}

Para verificar a assinatura de um JWT do Cognito, procure a chave pública com uma ID da chave correspondente ao cabeçalho do token. Use bibliotecas diferentes para verificar a assinatura do token e extrair valores, como expiração e nome de usuário.

É uma prática recomendada verificar se o token não expirou. Além disso, certifique-se de que o público (“aud”) no payload corresponda ao ID do cliente da aplicação que você criou no grupo de usuários do Amazon Cognito.A biblioteca aws-jwt-verify verifica esses valores para você. Para obter mais informações, consulte aws-jwt-verify no site do GitHub.

Armazenar chaves públicas em cache

Como as chaves públicas no endpoint JWKS raramente são alternadas, você não precisa baixá-las do endpoint sempre que verificar um token. Em vez disso, baixe as chaves públicas e armazene-as em cache na máquina local em que você usa a lógica de verificação do token JWT.

O “kid” é um identificador exclusivo para as chaves públicas. Para verificar um token JWT, verifique seu cache local para determinar se “kid” no cabeçalho do token está no cache. Se não houver cache, baixe as chaves públicas do endpoint JWKS e atualize seu cache.

Use métodos diferentes para verificar o status de expiração ou revogação de um token

Você pode revogar tokens de atualização e invalidar tokens de acesso, mas não pode revogar tokens de ID. As bibliotecas verificadoras do JWT verificam a expiração do token, mas não verificam o status de revogação de um token. Uma verificação do status de revogação exige uma verificação do lado do servidor.

Informações relacionadas

Entendendo os JSON Web Tokens (JWTs) do grupo de usuários

Como faço para revogar tokens JWT no Amazon Cognito usando a AWS CLI?