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

Descripción breve

Cuando los clientes se autentican en su aplicación con un grupo de usuarios, Amazon Cognito envía un token de ID. Puede verificar manualmente el token de ID en escenarios similares a los siguientes:

• Ha creado una aplicación web y desea utilizar un grupo de usuarios de Amazon Cognito para la autenticación.
• Utiliza un grupo de usuarios de Amazon Cognito para la autenticación y un grupo de identidades de Amazon Cognito para recuperar las credenciales temporales de AWS Security Token Service (AWS STS). AWS Lambda se invoca con esas credenciales, pero Lambda no tiene información sobre quién se autenticó originalmente con el grupo de usuarios.

Para obtener los detalles de usuario de Amazon Cognito incluidos en un token web JSON (JWT) de Amazon Cognito, puede decodificar el token y, a continuación, verificar la firma.

Resolución

AWS publicó la siguiente biblioteca que puede utilizar para verificar los JWT: https://github.com/awslabs/aws-jwt-verify

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!");
}

Cuando un usuario inicia sesión, un grupo de usuarios de Amazon Cognito devuelve un JWT. El JWT es una cadena JSON codificada en base64url («declaraciones») que contiene información sobre el usuario. Amazon Cognito devuelve tres tokens: el token de ID, el token de acceso y el token de actualización. El token de ID contiene los campos de usuario definidos en el grupo de usuarios de Amazon Cognito.

Los tokens incluyen tres secciones: un encabezado, una carga y una firma.

A continuación se muestra el encabezado de un token de ID de ejemplo. El encabezado contiene el identificador de clave («kid»), así como el algoritmo («alg») utilizado para firmar el token. En este ejemplo, el algoritmo es «RS256», que es una firma RSA con SHA-256.

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

El siguiente es un ejemplo de la carga útil, que contiene información sobre el usuario, así como las marcas de tiempo de creación y caducidad del token:

{
  "sub": "aaaaaaaa-bbbb-cccc-dddd-example",
  "aud": "xxxxxxxxxxxxexample",
  "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 última sección es la firma, que 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 utiliza para firmar el token de ID o el token de acceso respectivos. Las claves públicas están disponibles en una dirección con el siguiente formato:

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

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 Amazon Cognito, primero busque la clave pública con un ID de clave que coincida con el ID de clave del encabezado del token. A continuación, puede utilizar bibliotecas, como aws-jwt-verify o las recomendadas por jwt.io u OpenID Foundation, para validar la firma del token y extraer valores, como la caducidad y el nombre de usuario.

Además de la firma, también se recomienda comprobar lo siguiente:

• El token no ha caducado.
• La audiencia («aud») especificada en la carga coincide con el ID de cliente de la aplicación creado en el grupo de usuarios de Amazon Cognito.

La biblioteca aws-jwt-verify incluye estas comprobaciones en su nombre. Para obtener más ejemplos de código sobre cómo decodificar y verificar un Amazon Cognito JWT mediante Lambda, consulte Decodificar y verificar los tokens JWT de Amazon Cognito.

---

Información relacionada

Verificación de un token web JSON

Uso de tokens con grupos de usuarios