¿Cómo puedo decodificar y verificar la firma de un token web JSON de Amazon Cognito?

Descripción corta

Cuando los clientes utilizan un grupo de usuarios para autenticarse en su aplicación, Cognito envía un token web JSON (JWT) para que lo decodifique, lea y modifique. Para obtener los detalles de usuario de Cognito de un JWT, decodifique el token y verifique la firma.

Importante: Antes de conceder acceso a sus recursos, debe verificar la firma.

Resolución

Verificación de que Cognito haya emitido JWT

Use el siguiente código en 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!");
}

Nota: Sustituya user_pool_id por el ID de su grupo de usuarios y client_id por el ID del cliente de la aplicación. Para el token de ID, actualice el campo tokenUse a «id». Para obtener una lista de los parámetros disponibles, consulte aws-jwt-verify en el sitio web de GitHub.

Si utiliza otro lenguaje de programación, consulte jwt.io libraries en el sitio web de JWT o las bibliotecas de OpenID Connect en el sitio web de OpenID. Para ver un ejemplo de código, consulte Decode and verify Amazon Cognito JWT tokens en el sitio web de GitHub.

Cognito devuelve hasta tres tokens: el token de ID, el token de acceso y el token de actualización. Si usa API de REST, AWS Amplify o SDK de AWS para autenticar a un usuario, obtendrá los tres tokens.

En la interfaz de usuario alojada en Cognito, el token que se obtiene depende del tipo de concesión de autorización que se utilice. Si usa la concesión implícita, solo obtendrá el token de acceso e ID. La concesión del código de autorización devuelve los tokens de acceso, ID y actualización. La concesión de credenciales de cliente devuelve solo el token de acceso.

Los tokens de acceso e ID incluyen un encabezado, una carga útil y una firma. El cliente no puede decodificar ni verificar el token de actualización.

El siguiente es un ejemplo de encabezado de token de ID. El encabezado contiene el ID de clave («kid») y el algoritmo («alg») utilizado para firmar el token. El algoritmo RS256 es una firma RSA con SHA-256:

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

El siguiente es un ejemplo de una carga útil que contiene información sobre el usuario y las marcas de tiempo de la creación y vencimiento del 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"
}

La firma es una combinación cifrada y encriptada del encabezado y la carga útil.

Amazon Cognito genera dos pares de claves RSA para cada grupo de usuarios. La clave privada de cada par se usa para firmar criptográficamente el token de ID o el token de acceso. Puede encontrar las claves públicas en una dirección en la siguiente ubicación:

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

Nota: Sustituya region por la región de AWS en la que se encuentra su grupo de usuarios y userPoolID por el ID de su grupo de usuarios.

El archivo JSON (jwks.json) está estructurado en el siguiente 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 la firma de un JWT de Cognito, busque la clave pública con un ID de clave que coincida con el encabezado del token. Use diferentes bibliotecas para verificar la firma del token y extraer valores, como el vencimiento y el nombre de usuario.

Se recomienda verificar que el token no haya vencido. Además, asegúrese de que la audiencia («aud») de la carga útil coincida con el ID de cliente de la aplicación que creó en el grupo de usuarios de Amazon Cognito. La biblioteca aws-jwt-verify comprueba estos valores en su nombre. Para obtener más información, consulte aws-jwt-verify en el sitio web de GitHub.

Almacenamiento en caché de las claves públicas

Como las claves públicas del punto de enlace de JWKS rara vez se rotan, no es necesario descargarlas del punto de enlace cada vez que verifique un token. En su lugar, descargue las claves públicas y guárdelas en caché en la máquina local en la que utilice la lógica de verificación del token de JWT.

El «kid» es un identificador único para las claves públicas. Para verificar un token de JWT, compruebe su caché local para determinar si el «kid» del encabezado del token está en la caché. Si no hay caché, descargue las claves públicas del punto de enlace de JWKS y actualice la caché.

Uso de diferentes métodos para comprobar el estado de vencimiento o revocación de un token

Puede revocar los tokens de actualización e invalidar los de acceso, pero no puede revocar los tokens de ID. Las bibliotecas verificadoras de JWT verifican el vencimiento del token, pero no comprueban el estado de revocación del token. La verificación del estado de revocación requiere una verificación del servidor.

Información relacionada

Descripción de los tokens JSON web de grupos de usuarios (JWTs)

¿Cómo puedo revocar los tokens JWT en Amazon Cognito mediante la AWS CLI?