Claim JWT Personalizzati

I claim personalizzati consentono di incorporare dati aggiuntivi direttamente nel JWT access token emesso da Auris. Invece di effettuare una chiamata API separata per recuperare i dati utente dopo l’autenticazione, il tuo backend può leggere il claim direttamente dal token verificato.

I claim personalizzati vengono configurati per applicazione nella Console e risolti al momento dell’emissione del token.

Quando Usare i Claim Personalizzati

I claim personalizzati sono utili quando:

• Il tuo backend ha bisogno di metadati utente (dipartimento, piano, tenant ID) su ogni richiesta senza una ricerca aggiuntiva
• Un’API di terze parti si aspetta claim specifici nel JWT (es. un gateway di pagamento che si aspetta un claim subscription_tier)
• Vuoi codificare informazioni su permessi o ruoli nel token per un’autorizzazione stateless
• Diverse applicazioni nel tuo tenant necessitano di dati utente diversi nei loro token

Tipi di Claim

Auris supporta quattro tipi di valori per i claim:

STATIC

Un valore stringa, numerico o booleano fisso — lo stesso per ogni utente che riceve un token da questa applicazione.

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

Usa quando: Devi identificare quale applicazione ha emesso il token, o incorporare valori di configurazione che non cambiano per utente.

USER_ATTRIBUTE

Un valore derivato dal profilo dell’utente autenticato. Gli attributi disponibili sono:

{ "user_email": "[email protected]" }
{ "department": "engineering" }   // tramite metadata.department
{ "phone": "+39 333 1234567" }

Usa quando: Il tuo backend o servizio downstream ha bisogno dei dati di identità utente disponibili nel token senza chiamate API aggiuntive.

ROLE_BASED

Un valore diverso restituito in base ai ruoli che l’utente possiede. Il primo ruolo corrispondente vince. Un valore di fallback viene restituito se nessun ruolo corrisponde.

// Configurazione:
{
  "plan": {
    "Amministratore": "enterprise",
    "Utente Pro": "pro",
    "default": "free"
  }
}
 
// Claim risultante per un Utente Pro: { "plan": "pro" }
// Claim risultante per un Amministratore: { "plan": "enterprise" }
// Claim risultante per un utente senza ruolo corrispondente: { "plan": "free" }

Usa quando: Ruoli diversi nel tuo sistema corrispondono a livelli di funzionalità, livelli di accesso o piani tariffari su cui i servizi downstream devono agire.

EXPRESSION

Un valore calcolato usando una semplice espressione valutata nel contesto utente. Le espressioni hanno accesso alle variabili user, roles e metadata.

// Le espressioni sono simili a JavaScript (valutate in un contesto sandbox)
user.email.split('@')[1]           // => "acme.com" (dominio email)
roles.includes('Amministratore')   // => true | false
metadata.orgId ?? 'default'        // => orgId dai metadati o "default"
user.firstName + ' ' + user.lastName  // => "Mario Rossi"

Usa quando: Hai bisogno di un valore derivato o calcolato che non è direttamente disponibile come attributo utente.

Claim Riservati

Le seguenti chiavi di claim sono riservate da Auris e dalla specifica OAuth2/OIDC. Non possono essere sovrascritte dai claim personalizzati:

Tentare di creare un claim personalizzato con una chiave riservata restituisce un errore di validazione.

Configurazione nella Console

Esempi

Esempio 1: Incorporare il Dipartimento dell’Utente

Requisito: Il tuo backend deve conoscere il dipartimento dell’utente su ogni richiesta.

Configurazione:

• Claim Key: department
• Tipo: USER_ATTRIBUTE
• Attributo: metadata.department

Token risultante:

{
  "sub": "user-id-123",
  "email": "[email protected]",
  "roles": ["Dipendente"],
  "department": "Engineering",
  ...claim standard...
}

Utilizzo nel backend:

// Nessuna chiamata API aggiuntiva — il dipartimento è già nel token
const { department } = verifyToken(req.headers.authorization.slice(7))
console.log(department) // "Engineering"

Esempio 2: Badge Piano di Abbonamento

Requisito: Uno strumento di analytics di terze parti si aspetta un claim subscription_plan che indica il livello dell’utente.

Configurazione:

• Claim Key: subscription_plan
• Tipo: ROLE_BASED
• Mapping:
  • Cliente Enterprise → enterprise
  • Cliente Pro → pro
  • Piano Gratuito → free
  • Default → free

Token risultante per un Cliente Enterprise:

{
  "sub": "user-id-456",
  "roles": ["Cliente Enterprise", "Visualizzatore Fatture"],
  "subscription_plan": "enterprise",
  ...
}

Esempio 3: Estrazione del Dominio Email

Requisito: Un backend multi-tenant instrada le richieste in base al dominio email dell’utente (azienda).

Configurazione:

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

Token risultante:

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

Esempio 4: Ambiente Applicazione Statico

Requisito: Distinguere i token dall’applicazione di produzione rispetto a quella di staging.

Configurazione (sull’app di produzione):

• Claim Key: env
• Tipo: STATIC
• Valore: production

Configurazione (sull’app di staging):

• Claim Key: env
• Tipo: STATIC
• Valore: staging

Endpoint API

Considerazioni sulla Dimensione del Token

Ogni claim personalizzato si aggiunge alla dimensione di ogni JWT access token emesso dall’applicazione. I token JWT vengono inviati come header HTTP su ogni richiesta autenticata. Mantieni i claim concisi:

Token troppo grandi possono causare errori 431 Request Header Fields Too Large su alcuni proxy e load balancer (tipicamente con header superiori a 8KB).

Guide Correlate

• Ruoli e Permessi (RBAC) — Configurazione dei ruoli referenziata dai claim ROLE_BASED
• Autorizzazione Granulare (FGA) — Autorizzazione a livello di oggetto usando FGA
• Client Credentials M2M — I claim personalizzati si applicano anche ai token M2M