Referencia para desarrolladores JWT

Referencia de Claims JWT

Al depurar JWT leo cada claim en contexto: quién lo emitió, para quién, cuándo es válido y qué datos de autorización entiende la aplicación.

48 / 48

Claims JWT registrados

iss

Emisor

stringRFC 7519 §4.1.1

Identifica quién emitió el JWT.

Validación: Comparar exactamente con un issuer que la aplicación ya confíe.

sub

Sujeto

stringRFC 7519 §4.1.2

Identifica el sujeto representado por el JWT dentro del namespace del issuer.

Validación: Interpretar solo dentro del namespace del issuer después de validarlo.

aud

Audiencia

string | string[]RFC 7519 §4.1.3

Identifica los destinatarios previstos del JWT.

Validación: Exigir que esté presente la audiencia esperada por el resource server.

exp

Expiración

NumericDateRFC 7519 §4.1.4

Hora después de la cual el JWT no debe aceptarse.

Validación: Rechazar después de exp permitiendo solo una pequeña tolerancia configurada.

nbf

No antes de

NumericDateRFC 7519 §4.1.5

Hora antes de la cual el JWT no debe aceptarse.

Validación: Rechazar antes de nbf salvo la tolerancia de reloj configurada.

iat

Emitido en

NumericDateRFC 7519 §4.1.6

Hora en la que se emitió el JWT.

Validación: Usar para políticas de edad/vida útil y rechazar valores futuros poco plausibles.

jti

ID JWT

stringRFC 7519 §4.1.7

Identificador único del JWT.

Validación: Combinar con estado del servidor solo si replay o revocación requieren unicidad.

Identidad e ID Token OpenID Connect

azp

Parte autorizada

stringOIDC Core §2

Identifica la parte para la que se emitió el ID Token.

Validación: Comprobar cuando haya varias audiencias o lo exija la política del cliente.

nonce

Nonce

stringOIDC Core §2

Vincula un ID Token con la solicitud de autenticación del navegador/cliente.

Validación: Comparar exactamente con el nonce guardado para la solicitud de autorización.

auth_time

Hora de autenticación

NumericDateOIDC Core §2

Momento en el que ocurrió la autenticación del usuario.

Validación: Usar cuando max_age o la reautenticación dependen de la antigüedad de la autenticación.

acr

Clase de contexto de autenticación

stringOIDC Core §2

Clase de contexto de autenticación alcanzada.

Validación: Aceptar solo niveles de assurance que la aplicación reconozca explícitamente.

amr

Métodos de autenticación

string[]OIDC Core §2

Métodos usados realmente para autenticar al usuario.

Validación: No inferir assurance de valores desconocidos; seguir la semántica del issuer.

at_hash

Hash del Access Token

stringOIDC Core §3.1.3.6

Valor derivado de hash que vincula un Access Token con un ID Token.

Validación: Validar cuando el flow/response type OIDC lo requiera.

c_hash

Hash del código de autorización

stringOIDC Core §3.3.2.11

Valor derivado de hash que vincula un código de autorización con un ID Token.

Validación: Validar cuando el response type OIDC lo requiera.

s_hash

Hash de state

stringOIDC FAPI / registered claim

Vincula state con una respuesta firmada en determinados perfiles OIDC/FAPI.

Validación: Validar solo cuando el perfil OIDC/FAPI activo lo exija.

sid

ID de sesión

stringOpenID Connect Session Management

Identifica una sesión del OpenID Provider.

Validación: Tratar como metadata de sesión del issuer, no como ID global de usuario.

name

Nombre completo

stringOIDC Core §5.1

Nombre completo de presentación del usuario.

Validación: Dato de perfil; no usar como identificador estable de autorización.

given_name

Nombre

stringOIDC Core §5.1

Nombre del usuario.

Validación: Dato de presentación; considerar localización.

family_name

Apellidos

stringOIDC Core §5.1

Apellidos del usuario.

Validación: No asumir unicidad.

middle_name

Segundo nombre

stringOIDC Core §5.1

Segundo nombre del usuario.

Validación: Tratar como dato de perfil opcional.

nickname

Apodo

stringOIDC Core §5.1

Apodo del usuario.

Validación: Usar solo para presentación.

preferred_username

Usuario preferido

stringOIDC Core §5.1

Nombre corto preferido por el usuario.

Validación: No asumir unicidad global ni inmutabilidad.

profile

URL de perfil

URL stringOIDC Core §5.1

URL de la página de perfil.

Validación: Validar el manejo de URL antes de renderizar enlaces.

picture

URL de imagen

URL stringOIDC Core §5.1

URL de la imagen de perfil.

Validación: Tratar como contenido remoto no confiable al renderizar.

website

URL del sitio web

URL stringOIDC Core §5.1

URL del sitio web del usuario.

Validación: Tratar como dato de perfil no confiable.

email

Correo electrónico

stringOIDC Core §5.1

Dirección de correo preferida.

Validación: Solo tratar como verificado si email_verified=true y el issuer es confiable.

email_verified

Correo verificado

booleanOIDC Core §5.1

Indica si el issuer verificó el control del correo.

Validación: Confiar solo junto a un issuer y método de verificación conocidos.

gender

Género

stringOIDC Core §5.1

Valor de género proporcionado por el issuer.

Validación: Minimizar la recogida si no es necesario.

birthdate

Fecha de nacimiento

stringOIDC Core §5.1

Fecha de nacimiento del usuario.

Validación: Dato sensible; no usar como factor de autenticación.

zoneinfo

Zona horaria

stringOIDC Core §5.1

Identificador de zona horaria.

Validación: Usar solo para presentación/preferencias.

locale

Configuración regional

BCP 47 stringOIDC Core §5.1

Preferencia regional/idioma del usuario.

Validación: Usar para presentación, no para decisiones de confianza.

phone_number

Número de teléfono

stringOIDC Core §5.1

Número de teléfono preferido.

Validación: Solo tratar como verificado si phone_number_verified=true y el issuer es confiable.

phone_number_verified

Teléfono verificado

booleanOIDC Core §5.1

Indica si el issuer verificó el control del número.

Validación: Interpretar según la política y método de verificación del issuer.

address

Dirección postal

objectOIDC Core §5.1

Objeto estructurado de dirección postal.

Validación: Validar campos anidados antes de mostrar y tratar como dato sensible.

updated_at

Actualización del perfil

NumericDateOIDC Core §5.1

Momento de la última actualización del perfil.

Validación: Usar únicamente como metadata de frescura del perfil.

Access Token OAuth y autorización

client_id

ID de cliente

stringRFC 9068 §2.2

Identifica el cliente OAuth asociado al Access Token.

Validación: Comparar solo si la política del resource server depende de un cliente concreto.

scope

Scopes OAuth

space-delimited stringRFC 9068 §2.2.3 / RFC 8693

Permisos delegados asociados al Access Token.

Validación: Autorizar solo scopes conocidos por el recurso y aplicables a la audience.

roles

Roles

string[]RFC 9068 §2.2.3.1 / RFC 7643

Valores de rol usados en autorización.

Validación: Definir semántica issuer/resource y rechazar roles desconocidos por defecto.

groups

Grupos

string[]RFC 9068 §2.2.3.1 / RFC 7643

Pertenencia a grupos usada en decisiones de autorización.

Validación: No asumir nombres o jerarquías comunes entre issuers.

entitlements

Derechos

string[]RFC 9068 §2.2.3.1 / RFC 7643

Derechos o privilegios asociados al sujeto.

Validación: Mapear explícitamente cada entitlement a una acción permitida.

cnf

Confirmación

objectRFC 7800

Información de confirmación para una clave proof-of-possession.

Validación: Validar realmente el método de confirmación exigido por el token/perfil.

act

Actor

objectRFC 8693 §4.1

Identifica al actor real en delegación o impersonation.

Validación: Distinguir actor y sujeto al autorizar y auditar.

may_act

Puede actuar

objectRFC 8693 §4.4

Identifica las partes autorizadas a actuar por el sujeto.

Validación: Usar solo con una política explícita de delegación/token exchange.

Autorización privada / proveedor

permissions

Permisos

string[]Private claim

Lista privada de acciones permitidas por la aplicación.

Validación: Definir issuer, audience y semántica de cada permiso privado.

role

Rol

string | string[]Private claim

Convención privada para uno o varios roles.

Validación: No asumir equivalencia con roles; mapear por issuer.

tenant

Tenant

stringPrivate claim

Convención privada para routing de tenant u organización.

Validación: Nunca establecer confianza del issuer solo con tenant; contrastar con contexto autenticado.

org_id

ID de organización

stringPrivate claim

Identificador de organización común en modelos SaaS.

Validación: Tratar como valor específico del issuer y exigir membership de recurso por separado.

token_use

Uso del token

stringVendor/private claim

Convención de proveedor para distinguir tokens access/identity.

Validación: Usar solo si está documentado por el issuer; preferir reglas estándar typ/profile.