Claims JWT Personalizados

Los claims personalizados te permiten incrustar datos adicionales directamente en el JWT de acceso emitido por Auris. En lugar de hacer una llamada API adicional para obtener datos del usuario después de la autenticación, tu backend puede leer el claim directamente desde el token verificado.

Los claims personalizados se configuran por aplicación en la Consola y se resuelven en el momento de la emisión del token.

Cuándo Usar Claims Personalizados

Los claims personalizados son útiles cuando:

• Tu backend necesita metadatos del usuario (departamento, plan, ID de tenant) en cada solicitud sin una consulta adicional
• Una API de terceros espera claims específicos en el JWT (por ejemplo, una pasarela de pago que espera un claim subscription_tier)
• Quieres codificar información de permisos o roles en el token para autorización sin estado
• Diferentes aplicaciones en tu tenant necesitan datos de usuario distintos en sus tokens

Tipos de Claim

Auris soporta cuatro tipos de valor para los claims:

STATIC

Un valor fijo de tipo string, número o booleano — el mismo para todos los usuarios que reciben un token de esta aplicación.

{ "environment": "production" }
{ "app_version": "2.1.0" }
{ "feature_flag_x": true }

Úsalo cuando: Necesitas identificar qué aplicación emitió el token, o incrustar valores de configuración que no cambian por usuario.

USER_ATTRIBUTE

Un valor extraído del perfil del usuario autenticado. Los atributos disponibles son:

{ "user_email": "[email protected]" }
{ "department": "engineering" }   // via metadata.department
{ "phone": "+15551234567" }

Úsalo cuando: Tu backend o servicio downstream necesita datos de identidad del usuario disponibles en el token sin llamadas API adicionales.

ROLE_BASED

Un valor diferente devuelto según qué roles tiene el usuario. Gana la primera coincidencia de rol. Se devuelve un valor de fallback si no coincide ningún rol.

// Configuración:
{
  "plan": {
    "Administrator": "enterprise",
    "Pro User": "pro",
    "default": "free"
  }
}
 
// Claim resultante para un Pro User: { "plan": "pro" }
// Claim resultante para un Administrator: { "plan": "enterprise" }
// Claim resultante para un usuario sin rol coincidente: { "plan": "free" }

Úsalo cuando: Diferentes roles en tu sistema corresponden a niveles de funcionalidades, niveles de acceso o planes de precios sobre los que los servicios downstream necesitan actuar.

EXPRESSION

Un valor calculado usando una expresión simple evaluada contra el contexto del usuario. Las expresiones tienen acceso a las variables user, roles y metadata.

// Las expresiones son similares a JavaScript (evaluadas en un contexto aislado)
user.email.split('@')[1]           // => "acme.com" (dominio del email)
roles.includes('Administrator')    // => true | false
metadata.orgId ?? 'default'        // => orgId de los metadatos o "default"
user.firstName + ' ' + user.lastName  // => "Alice Smith"

Úsalo cuando: Necesitas un valor derivado o calculado que no está disponible directamente como atributo de usuario.

Claims Reservados

Las siguientes claves de claim están reservadas por Auris y por la especificación OAuth2/OIDC. No pueden ser anuladas por claims personalizados:

Intentar crear un claim personalizado con una clave reservada devuelve un error de validación.

Configuración en la Consola

Ejemplos

Ejemplo 1: Incrustar el Departamento del Usuario

Requisito: Tu backend necesita conocer el departamento del usuario en cada solicitud.

Configuración:

• Clave del Claim: department
• Tipo: USER_ATTRIBUTE
• Atributo: metadata.department

Token resultante:

{
  "sub": "user-id-123",
  "email": "[email protected]",
  "roles": ["Employee"],
  "department": "Engineering",
  ...claims estándar...
}

Uso en el backend:

// Sin llamada API adicional — el departamento está en el token
const { department } = verifyToken(req.headers.authorization.slice(7))
console.log(department) // "Engineering"

Ejemplo 2: Insignia de Plan de Suscripción

Requisito: Una herramienta de análisis de terceros espera un claim subscription_plan que indique el nivel del usuario.

Configuración:

• Clave del Claim: subscription_plan
• Tipo: ROLE_BASED
• Mapeo:
  • Enterprise Customer → enterprise
  • Pro Customer → pro
  • Free Tier → free
  • Predeterminado → free

Token resultante para un Enterprise Customer:

{
  "sub": "user-id-456",
  "roles": ["Enterprise Customer", "Invoice Viewer"],
  "subscription_plan": "enterprise",
  ...
}

Ejemplo 3: Extracción del Dominio de Email

Requisito: Un backend multi-tenant enruta las solicitudes según el dominio de email del usuario (empresa).

Configuración:

• Clave del Claim: email_domain
• Tipo: EXPRESSION
• Expresión: user.email.split('@')[1]

Token resultante:

{
  "sub": "user-id-789",
  "email": "[email protected]",
  "email_domain": "contoso.com",
  ...
}

Ejemplo 4: Entorno de Aplicación Estático

Requisito: Distinguir los tokens de los registros de aplicaciones de producción frente a los de staging.

Configuración (en la app de producción):

• Clave del Claim: env
• Tipo: STATIC
• Valor: production

Configuración (en la app de staging):

• Clave del Claim: env
• Tipo: STATIC
• Valor: staging

Endpoints de la API

Consideraciones sobre el Tamaño del Token

Cada claim personalizado aumenta el tamaño de cada JWT de acceso emitido por la aplicación. Los tokens JWT se envían como cabeceras HTTP en cada solicitud autenticada. Mantén los claims concisos:

Los tokens demasiado grandes pueden causar errores 431 Request Header Fields Too Large en algunos proxies y balanceadores de carga (típicamente con cabeceras superiores a 8KB).

Guías Relacionadas

• Roles y Permisos (RBAC) — Configuración de roles referenciada por los claims ROLE_BASED
• Autorización de Grano Fino — Autorización a nivel de objeto usando FGA
• Credenciales M2M (Client Credentials) — Los claims personalizados también se aplican a los tokens M2M