🎫
← Volver a guías

Estructura del token JWT explicada: Header, Payload y Signature

· Etiquetas: jwt-structure, jwt-header, jwt-payload, jwt-signature, json-web-token

Estructura del token JWT explicada

Todo JSON Web Token (JWT) es una cadena compacta y segura para URL que transporta claims entre dos partes. Comprender su estructura interna es esencial para cualquier desarrollador que trabaje con seguridad basada en tokens.

Las tres partes de un JWT

Un JWT consta de tres partes separadas por puntos (.):

header.payload.signature

Ejemplo:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Cada parte es JSON codificado en base64url. Un JWT está firmado, no cifrado: cualquiera puede decodificarlo y leer su contenido.

Parte 1: El Header

El header contiene metadatos sobre el token: el algoritmo de firma y el tipo de token.

| Campo | Descripción | Valores de ejemplo | |-------|-------------|----------------| | alg | Algoritmo de firma (obligatorio) | HS256, RS256, ES256 | | typ | Tipo de token (opcional) | JWT | | kid | ID de clave (opcional) | "key-1" |

{
  "alg": "HS256",
  "typ": "JWT"
}

El campo alg indica al verificador qué algoritmo generó la signature. Una discrepancia de algoritmo — o aceptar alg: "none" — es una vulnerabilidad de seguridad común en JWT.

Parte 2: El Payload

El payload contiene claims sobre el usuario y metadatos. Los claims se dividen en tres categorías:

Registered Claims

| Claim | Nombre completo | Propósito | |-------|-----------|---------| | iss | Issuer (emisor) | Quién emitió el token | | sub | Subject (sujeto) | Identifica al usuario | | aud | Audience (audiencia) | Destinatario previsto | | exp | Expiration (expiración) | Marca de tiempo de caducidad del token | | nbf | Not Before (no antes de) | El token no es válido antes de este momento | | iat | Issued At (emitido en) | Marca de tiempo de creación del token | | jti | JWT ID | Identificador único del token |

Ejemplo de payload decodificado

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622,
  "iss": "https://auth.example.com"
}

Los public claims se definen en el registro de la IANA o utilizan URIs resistentes a colisiones. Los private claims son claims personalizados acordados entre el emisor y el consumidor.

Parte 3: La Signature

La signature se crea combinando el header codificado, el payload codificado y una clave secreta mediante el algoritmo del header. Cumple dos propósitos:

  1. Integrity (integridad) — confirma que el token no fue modificado después de firmarse.
  2. Authentication (autenticación) — demuestra que el token fue firmado por la parte esperada.

Creación de la signature HS256

HMACSHA256(
  base64urlEncode(header) + "." + base64urlEncode(payload),
  secret
)

Creación de la signature RS256

RSASHA256(
  base64urlEncode(header) + "." + base64urlEncode(payload),
  privateKey
)

Base64url frente a Base64 estándar

| Aspecto | Base64 estándar | Base64url | |--------|-----------------|-----------| | Carácter 62 | + | - | | Carácter 63 | / | _ | | Relleno (padding) | = | Omitido |

Esta codificación garantiza que los JWT sean seguros para headers HTTP, parámetros de consulta y rutas URL sin necesidad de percent-encoding.

Proceso completo de creación de un JWT

  1. Crea el JSON del header y codifícalo en base64url.
  2. Crea el JSON del payload y codifícalo en base64url.
  3. Concatena con un separador ..
  4. Firma con el algoritmo y la clave secreta elegidos.
  5. Codifica la signature en base64url.
  6. Concatena las tres partes con separadores ..

Consideraciones de seguridad

  • Nunca almacenes secretos en el payload. El payload está codificado, no cifrado.
  • Valida siempre la signature. Sin verificación, cualquiera puede falsificar tokens.
  • Comprueba el header alg. Rechaza alg: "none" y los intentos de degradación del algoritmo.
  • Establece tiempos de expiración cortos. Usa claims exp en minutos u horas, no en meses.

Decodifica un token JWT en línea

Usa la herramienta de decodificador de JWT para examinar cualquier token. Pégalo y verás al instante el header, el payload y el algoritmo de firma decodificados. Todo el procesamiento ocurre en tu navegador.

Estructura del token JWT explicada: Header, Payload y Signature - CoolTool