Claims JWT Personnalisés

Les claims personnalisés permettent d’intégrer des données supplémentaires directement dans le JWT access token émis par Auris. Au lieu d’effectuer un appel API séparé pour récupérer les données utilisateur après l’authentification, ton backend peut lire le claim directement depuis le token vérifié.

Les claims personnalisés sont configurés par application dans la Console et résolus au moment de l’émission du token.

Quand Utiliser les Claims Personnalisés

Les claims personnalisés sont utiles quand :

• Ton backend a besoin de métadonnées utilisateur (département, plan, tenant ID) sur chaque requête sans recherche supplémentaire
• Une API tierce s’attend à des claims spécifiques dans le JWT (ex. une passerelle de paiement qui attend un claim subscription_tier)
• Tu veux encoder des informations de permissions ou rôles dans le token pour une autorisation stateless
• Différentes applications dans ton tenant ont besoin de données utilisateur différentes dans leurs tokens

Types de Claims

Auris supporte quatre types de valeurs pour les claims :

STATIC

Une valeur de chaîne, numérique ou booléenne fixe — la même pour chaque utilisateur qui reçoit un token de cette application.

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

Utilise quand : Tu dois identifier quelle application a émis le token, ou intégrer des valeurs de configuration qui ne changent pas par utilisateur.

USER_ATTRIBUTE

Une valeur dérivée du profil de l’utilisateur authentifié. Les attributs disponibles sont :

{ "user_email": "[email protected]" }
{ "department": "engineering" }   // via metadata.department
{ "phone": "+33 6 12 34 56 78" }

Utilise quand : Ton backend ou service en aval a besoin des données d’identité utilisateur disponibles dans le token sans appels API supplémentaires.

ROLE_BASED

Une valeur différente retournée selon les rôles que l’utilisateur possède. Le premier rôle correspondant gagne. Une valeur de fallback est retournée si aucun rôle ne correspond.

// Configuration :
{
  "plan": {
    "Administrateur": "enterprise",
    "Utilisateur Pro": "pro",
    "default": "free"
  }
}
 
// Claim résultant pour un Utilisateur Pro : { "plan": "pro" }
// Claim résultant pour un Administrateur : { "plan": "enterprise" }
// Claim résultant pour un utilisateur sans rôle correspondant : { "plan": "free" }

Utilise quand : Différents rôles dans ton système correspondent à des niveaux de fonctionnalité, niveaux d’accès ou plans tarifaires sur lesquels les services en aval doivent agir.

EXPRESSION

Une valeur calculée en utilisant une expression simple évaluée dans le contexte utilisateur. Les expressions ont accès aux variables user, roles et metadata.

// Les expressions sont similaires à JavaScript (évaluées dans un contexte sandbox)
user.email.split('@')[1]           // => "acme.com" (domaine e-mail)
roles.includes('Administrateur')   // => true | false
metadata.orgId ?? 'default'        // => orgId depuis les métadonnées ou "default"
user.firstName + ' ' + user.lastName  // => "Marie Dupont"

Utilise quand : Tu as besoin d’une valeur dérivée ou calculée qui n’est pas directement disponible comme attribut utilisateur.

Claims Réservés

Les clés de claims suivantes sont réservées par Auris et la spécification OAuth2/OIDC. Elles ne peuvent pas être écrasées par des claims personnalisés :

Tenter de créer un claim personnalisé avec une clé réservée retourne une erreur de validation.

Configuration dans la Console

Exemples

Exemple 1 : Intégrer le Département de l’Utilisateur

Exigence : Ton backend doit connaître le département de l’utilisateur sur chaque requête.

Configuration :

• Claim Key : department
• Type : USER_ATTRIBUTE
• Attribut : metadata.department

Token résultant :

{
  "sub": "user-id-123",
  "email": "[email protected]",
  "roles": ["Employé"],
  "department": "Engineering",
  ...claims standard...
}

Utilisation dans le backend :

// Aucun appel API supplémentaire — le département est déjà dans le token
const { department } = verifyToken(req.headers.authorization.slice(7))
console.log(department) // "Engineering"

Exemple 2 : Badge de Plan d’Abonnement

Exigence : Un outil d’analytics tiers s’attend à un claim subscription_plan indiquant le niveau de l’utilisateur.

Configuration :

• Claim Key : subscription_plan
• Type : ROLE_BASED
• Mapping :
  • Client Enterprise → enterprise
  • Client Pro → pro
  • Plan Gratuit → free
  • Default → free

Token résultant pour un Client Enterprise :

{
  "sub": "user-id-456",
  "roles": ["Client Enterprise", "Visualiseur Factures"],
  "subscription_plan": "enterprise",
  ...
}

Exemple 3 : Extraction du Domaine E-mail

Exigence : Un backend multi-tenant route les requêtes selon le domaine e-mail de l’utilisateur (entreprise).

Configuration :

• Claim Key : email_domain
• Type : EXPRESSION
• Expression : user.email.split('@')[1]

Token résultant :

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

Exemple 4 : Environnement d’Application Statique

Exigence : Distinguer les tokens de l’application de production versus celle de staging.

Configuration (sur l’app de production) :

• Claim Key : env
• Type : STATIC
• Valeur : production

Configuration (sur l’app de staging) :

• Claim Key : env
• Type : STATIC
• Valeur : staging

Endpoints API

Considérations sur la Taille du Token

Chaque claim personnalisé s’ajoute à la taille de chaque JWT access token émis par l’application. Les tokens JWT sont envoyés comme header HTTP sur chaque requête authentifiée. Garde les claims concis :

Des tokens trop volumineux peuvent causer des erreurs 431 Request Header Fields Too Large sur certains proxies et load balancers (typiquement avec des headers supérieurs à 8KB).

Guides Associés

• Rôles et Permissions (RBAC) — Configuration des rôles référencée par les claims ROLE_BASED
• Autorisation Fine-Grained (FGA) — Autorisation au niveau objet utilisant FGA
• Credentials M2M Client — Les claims personnalisés s’appliquent aussi aux tokens M2M