Benutzerdefinierte JWT-Claims

Benutzerdefinierte JWT-Claims ermöglichen es dir, anwendungsspezifische Daten zu den Access Tokens deiner Benutzer hinzuzufügen. Anstatt bei jeder Anfrage deine Datenbank nach Benutzermetadaten abzufragen, kannst du die benötigten Informationen in das Token einbetten und darauf aus deinen Backends und Frontends zugreifen — ohne zusätzliche API-Aufrufe.

Häufige Anwendungsfälle:

• Abteilung oder Kostenstelle eines Benutzers an den Token anhängen
• Abonnementplan oder Feature-Flags als Token-Claim einbetten
• Spracheinstellungen oder Theme-Präferenzen in Client-Libraries abrufbar machen
• Benutzerdefinierte IDs aus Drittanbieter-Systemen weitergeben (CRM-IDs, ERP-IDs, etc.)

Claim-Typen

Auris unterstützt vier Claim-Typen:

STATIC

Ein fester Wert, der sich nie ändert. Nützlich für das Einbetten von Umgebungsbezeichnern oder unveränderlichen Anwendungskonstanten.

{
  "type": "STATIC",
  "claimKey": "environment",
  "value": "production"
}

USER_ATTRIBUTE

Ein Wert aus dem Profil des authentifizierten Benutzers. Unterstützte Schlüssel:

{
  "type": "USER_ATTRIBUTE",
  "claimKey": "department",
  "attributeKey": "metadata.department"
}

ROLE_BASED

Ein Wert, der auf der Rolle des Benutzers basiert. Die erste übereinstimmende Rolle gewinnt; wenn keine Rolle übereinstimmt, wird der defaultValue verwendet.

{
  "type": "ROLE_BASED",
  "claimKey": "plan",
  "roleMapping": [
    { "role": "enterprise", "value": "enterprise" },
    { "role": "pro", "value": "pro" },
    { "role": "starter", "value": "starter" }
  ],
  "defaultValue": "free"
}

EXPRESSION

Ein benutzerdefinierter Ausdruck, der für jeden Token ausgewertet wird. Expressions werden in einer gesicherten Sandbox ausgeführt und haben Zugriff auf:

{
  "type": "EXPRESSION",
  "claimKey": "email_domain",
  "expression": "user.email.split('@')[1]"
}

Reservierte Claims

Die folgenden Claims sind von Auris reserviert und können nicht überschrieben werden:

Wenn du versuchst, einen dieser Claims zu überschreiben, gibt die API einen Validierungsfehler zurück.

Einrichten über die Console

1. Öffne die Auris Console → Applications und wähle deine Anwendung aus.
2. Navigiere zum Tab Custom Claims.
3. Klicke auf Add Claim.
4. Wähle Typ, Claim-Schlüssel und Quellkonfiguration (Wert, Attribut, Rollenzuordnung oder Expression).
5. Klicke auf Preview, um das genaue Payload für einen bestehenden Testbenutzer zu sehen.
6. Klicke auf Activate, um den Claim für alle neuen Token zu aktivieren.

Beispiele

Benutzer-Abteilung einbetten

Speichere die Abteilung im Benutzer-Metadaten-Feld und binde es als Claim ein:

{
  "type": "USER_ATTRIBUTE",
  "claimKey": "department",
  "attributeKey": "metadata.department",
  "defaultValue": "general"
}

Das resultierende Token-Payload enthält: "department": "engineering"

Abonnementplan als Badge

{
  "type": "ROLE_BASED",
  "claimKey": "subscription_plan",
  "roleMapping": [
    { "role": "enterprise", "value": "enterprise" },
    { "role": "pro", "value": "pro" },
    { "role": "starter", "value": "starter" }
  ],
  "defaultValue": "free"
}

E-Mail-Domain extrahieren (EXPRESSION)

Nützlich, um den E-Mail-Anbieter oder den Unternehmensbereich zu identifizieren:

{
  "type": "EXPRESSION",
  "claimKey": "email_domain",
  "expression": "user.email.split('@')[1]",
  "defaultValue": "unknown"
}

Statische Umgebungs-ID

{
  "type": "STATIC",
  "claimKey": "env",
  "value": "prod-eu-west-1"
}

Claims lesen

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({ domain: 'auth.yourdomain.com', clientId: 'your-client-id' })
 
const session = await auris.getSession()
const payload = session.decodedAccessToken
 
console.log(payload.department)         // 'engineering'
console.log(payload.subscription_plan)  // 'pro'
console.log(payload.email_domain)       // 'yourdomain.com'
console.log(payload.env)                // 'prod-eu-west-1'

Im Backend nach der Token-Verifizierung:

import { verifyToken } from '@auris/node'
 
const payload = await verifyToken(accessToken, {
  domain: process.env.AURIS_DOMAIN!,
  audience: process.env.AURIS_AUDIENCE!,
})
 
// Alle benutzerdefinierten Claims sind typisiert zugänglich
const department = payload.department as string
const plan = payload.subscription_plan as string

API-Referenz

Hinweise zur Token-Größe

HTTP-Server lehnen typischerweise Anfragen mit Headern über 8 KB ab. Da Access Tokens in Authorization: Bearer-Headern übertragen werden, gilt:

• Strings unter 100 Zeichen pro Claim-Wert halten
• Nicht mehr als 10 benutzerdefinierte Claims verwenden
• Keine vollständigen Metadaten-Objekte einbetten — nur metadata.{key}
• Keine Arrays einbetten, es sei denn, sie sind klein (z.B. 3–5 kurze Strings)
• Claims über die Preview-Funktion der Console testen, bevor du sie in der Produktion aktivierst

Verwandte Anleitungen

• Rollen & Berechtigungen (RBAC) — Rollenzuweisung, die von ROLE_BASED-Claims genutzt wird
• Token Exchange — Benutzerdefinierte Claims in ausgetauschten Tokens
• JavaScript SDK — decodedAccessToken-Payload-Zugriff