Tokens web JSON (JWT)

Tink admite la generación y verificación de JWT, que son un estándar muy usado en la Web. La implementación de JWT de Tink proporciona un subconjunto del estándar de JWT definido en RFC 7519 que el equipo de Tink considera seguro y que se adapta bien a la biblioteca Tink.

Tink no admite partes del estándar que rara vez se usan o que son difíciles de usar correctamente. Estas son las limitaciones:

• Tink solo admite el formato de serialización compacta de JWS. No se admiten la serialización JSON de JWS y JWE.
• Tink no admite el valor None en el encabezado alg.
• Tink solo admite los encabezados typ, alg y kid. Todos los demás encabezados no son compatibles.
• Tink no permite que se analicen tokens antes de que se verifique la firma o el MAC.

Firmas JWT

Si diferentes entidades generan y verifican los tokens, debes usar claves asimétricas con las primitivas JwtPublicKeySign y JwtPublicKeyVerify. La clave privada se usa para generar tokens y la pública se usa para verificarlos. Los algoritmos que admiten estas primitivas son los siguientes: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384 y PS512.

Elige un tipo de clave

Las firmas JWT usan tipos de claves diferentes a la firma digital normal de Tink. Esto es necesario porque algunos metadatos (como alg y kid) deben almacenarse con la clave.

Recomendamos usar JWT_ES256 en la mayoría de los casos de uso. Los tokens generados con este tipo de clave siempre tienen un encabezado kid. Si prefieres tokens un poco más cortos sin un encabezado kid, elige el tipo de clave JWT_ES256_RAW. Consulta Tipos de claves admitidos para conocer todos los tipos de claves admitidos.

Distribución del conjunto de claves públicas

Tink permite que el conjunto de claves públicas se convierta en y desde el formato de conjuntos de JWK definido en RFC 7517, que la mayoría de las bibliotecas JWT comprenden.

Nota: El formato de serialización del conjunto de claves JSON de Tink no es un conjunto de JWK y es probable que otras bibliotecas no puedan leerlo.

Tink no admite la exportación de claves JWT públicas en ningún otro formato. El motivo es que otros formatos no contienen los metadatos alg y kid que se usarán en la verificación, por lo que su uso es más propenso a errores y puede dificultar la rotación de claves.

Es preferible no solo compartir el conjunto de claves públicas una vez, sino también proporcionar una forma de actualizar automáticamente el conjunto. (Si no es así, rotar a una clave nueva es muy difícil). Para ello, se suele publicar el conjunto de claves públicas en una URL segura y confiable. Un servidor que verifica los tokens simplemente tiene que volver a recuperar periódicamente el conjunto de claves públicas de esa URL, por ejemplo, una vez al día. Para rotar la clave, debes agregar la nueva clave pública al conjunto de claves públicas al menos un día antes de que se use para firmar los tokens. De lo contrario, los servidores que aún usen el conjunto de claves públicas anterior rechazarán los tokens nuevos firmados con la nueva clave privada.

Nota: Algunas implementaciones vuelven a recuperar la clave pública en cuanto se recibe un token con un encabezado kid desconocido. No es posible implementar esta lógica en Tink, ya que el token no se analiza antes de que se verifique. No recomendamos hacer esto de todos modos, ya que puede generar muchas solicitudes adicionales a la URL del conjunto de claves si se envían tokens maliciosos con encabezados kid aleatorios.

MAC de JWT

Tink también admite JWT con claves simétricas con el JwtMac primitivo. Usa esta primitiva solo si la misma entidad genera y verifica los tokens. Los algoritmos compatibles con esta primitiva son HS256, HS384 y HS512.

Elige un tipo de clave

Los tipos de claves MAC de JWT son diferentes de los tipos de claves MAC normales. Recomendamos usar JWT_HS256 en la mayoría de los casos de uso.