Erstelle ein benutzerdefiniertes Token-Claims-Skript

Um benutzerdefinierte Ansprüche zum Zugangstoken hinzuzufügen, musst du ein Skript bereitstellen, das ein Objekt mit diesen Ansprüchen zurückgibt. Das Skript sollte als JavaScript-Funktion geschrieben werden, die ein Objekt mit den benutzerdefinierten Ansprüchen zurückgibt.

1. Navigiere zu Konsole > Benutzerdefinierte JWT.

2. Es gibt zwei verschiedene Arten von Zugangstokens, für die du die Zugangstoken-Ansprüche anpassen kannst:

   • Benutzer-Zugangstoken: Das Zugangstoken, das für Endbenutzer ausgestellt wird. Z.B. für Webanwendungen oder mobile Anwendungen.
   • Maschine-zu-Maschine Zugangstoken: Das Zugangstoken, das für die Dienste oder Anwendungen ausgestellt wird. Z.B. für Maschine-zu-Maschine-Anwendungen.

   Verschiedene Arten von Zugangstokens können unterschiedliche Token-Payload-Kontexte haben. Du kannst die Token-Ansprüche für jede Art von Zugangstoken separat anpassen.

   Wähle eine Art von Zugangstoken aus, für die du die Token-Ansprüche anpassen möchtest, und klicke auf die Schaltfläche Benutzerdefinierte Ansprüche hinzufügen, um ein neues Skript zu erstellen.

hinweis:

Die Funktion für benutzerdefinierte Token-Ansprüche ist nur verfügbar für:

• Logto OSS Benutzer
• Logto Cloud-Mieter mit Entwicklungsumgebung
• Logto Cloud bezahlte Mieter mit Produktionsumgebung (einschließlich Pro-Mieter und Enterprise-Mieter)

Implementiere die Funktion getCustomJwtClaims()

Auf der Benutzerdefinierte JWT-Detailseite findest du den Skript-Editor, um dein benutzerdefiniertes Token-Claims-Skript zu schreiben. Das Skript sollte eine JavaScript-Funktion sein, die ein Objekt mit benutzerdefinierten Ansprüchen zurückgibt.

Schritt 1: Bearbeite das Skript

Verwende den Code-Editor auf der linken Seite, um das Skript zu ändern. Ein Standard-getCustomJwtClaims mit einem leeren Objekt als Rückgabewert wird bereitgestellt, um dir den Einstieg zu erleichtern. Du kannst die Funktion ändern, um ein Objekt mit deinen eigenen benutzerdefinierten Ansprüchen zurückzugeben.

const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
  return {};
};

Dieser Editor verwendet den JavaScript-Sprachserver, um grundlegende Syntaxhervorhebung, Codevervollständigung und Fehlerprüfung bereitzustellen. Die Eingabeparameter sind gut typisiert und im jsDoc-Stil dokumentiert. Du kannst die IntelliSense des Editors verwenden, um die Eigenschaften des Eingabeobjekts korrekt zuzugreifen. Die detaillierten Parameterdefinitionen findest du auf der rechten Seite der Seite.

hinweis:

Diese Funktion wird als Modul exportiert. Stelle sicher, dass der Funktionsname als getCustomJwtClaims bleibt, damit das Modul die Funktion korrekt exportieren kann.

Schritt 2: Eingabeparameter

Die Funktion getCustomJwtClaims nimmt ein Objekt als Eingabeparameter. Das Eingabeobjekt enthält die folgenden Eigenschaften:

token

Das Token-Payload-Objekt. Dieses Objekt enthält ursprüngliche Token-Ansprüche und Metadaten, auf die du im Skript zugreifen musst.

Du findest die detaillierte Typdefinition des Token-Payload-Objekts und des Benutzerdatenobjekts auf der rechten Seite der Seite. Die IntelliSense des Editors hilft dir auch, diese Eigenschaften des Eingabeobjekts korrekt zuzugreifen.

• Benutzer-Zugangstoken-Datenobjekt

  Eigenschaft	Beschreibung	Typ
  jti	Die eindeutige JWT-ID	string
  aud	Die Zielgruppe des Tokens	string
  scope	Die Berechtigungen des Tokens	string
  clientId	Die Client-ID des Tokens	string
  accountId	Die Benutzer-ID des Tokens	string
  expiresWithSession	Ob das Token mit der Sitzung abläuft	boolean
  grantId	Die aktuelle Authentifizierungs-Grant-ID des Tokens	string
  gty	Der Grant-Typ des Tokens	string
  kind	Die Art des Tokens	AccessToken

• Maschine-zu-Maschine Zugangstoken-Datenobjekt

  Eigenschaft	Beschreibung	Typ
  jti	Die eindeutige JWT-ID	string
  aud	Die Zielgruppe des Tokens	string
  scope	Die Berechtigungen des Tokens	string
  clientId	Die Client-ID des Tokens	string
  kind	Die Art des Tokens	ClientCredentials

context (Nur verfügbar für Benutzer-Zugangstoken)

Das Kontextobjekt enthält die Benutzerdaten und Grant-Daten, die für den aktuellen Autorisierungsprozess relevant sind.

• Benutzerdatenobjekt Für Benutzer-Zugangstoken stellt Logto zusätzlichen Benutzerdatenkontext zur Verfügung, auf den du zugreifen kannst. Das Benutzerdatenobjekt enthält alle Benutzerdaten und Organisationsmitgliedschaftsdaten, die du benötigst, um die benutzerdefinierten Ansprüche einzurichten. Bitte sieh dir Benutzer und Organisationen für weitere Details an.
• Grant-Datenobjekt Für Benutzer-Zugangstoken, die durch Mimikry-Token-Austausch gewährt werden, stellt Logto zusätzlichen Grant-Datenkontext zur Verfügung, auf den du zugreifen kannst. Das Grant-Datenobjekt enthält den benutzerdefinierten Kontext aus dem Subjekt-Token. Bitte sieh dir Benutzermimikry für weitere Details an.

environmentVariables

Verwende den Abschnitt Umgebungsvariablen festlegen auf der rechten Seite, um die Umgebungsvariablen für dein Skript einzurichten. Du kannst diese Variablen verwenden, um sensible Informationen oder Konfigurationsdaten zu speichern, die du nicht im Skript fest codieren möchtest, z.B. API-Schlüssel, Geheimnisse oder URLs.

Alle hier festgelegten Umgebungsvariablen sind im Skript verfügbar. Verwende das environmentVariables-Objekt im Eingabeparameter, um auf diese Variablen zuzugreifen.

api

Das api-Objekt bietet eine Reihe von Dienstprogrammfunktionen, die du in deinem Skript verwenden kannst, um zusätzliche Zugangskontrolle über den Token-Ausstellungsprozess zu erhalten. Das api-Objekt enthält die folgenden Funktionen:

api.denyAccess(message?: string): void

Die Funktion api.denyAccess() ermöglicht es dir, den Token-Ausstellungsprozess mit einer benutzerdefinierten Nachricht zu verweigern. Du kannst diese Funktion verwenden, um zusätzliche Zugangsvalidierung über den Token-Ausstellungsprozess durchzusetzen.

Schritt 3: Externe Daten abrufen

Du kannst die eingebaute fetch-Funktion von Node verwenden, um externe Daten in deinem Skript abzurufen. Die fetch-Funktion ist eine auf Versprechen basierende Funktion, die es dir ermöglicht, HTTP-Anfragen an externe APIs zu stellen.

const getCustomJwtClaims = async ({ environmentVariables }) => {
  const response = await fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${environmentVariables.API_KEY}`,
    },
  });

  const data = await response.json();

  return {
    data,
  };
};

hinweis:

Sei dir bewusst, dass das Abrufen externer Daten Latenz in den Token-Ausstellungsprozess einführen kann. Stelle sicher, dass die externe API zuverlässig und schnell genug ist, um deine Anforderungen zu erfüllen.

Außerdem:

• Behandle Fehler und Zeitüberschreitungen in deinem Skript ordnungsgemäß, um zu vermeiden, dass der Token-Ausstellungsprozess blockiert wird.
• Verwende geeignete Autorisierungsheader, um deine externe API vor unbefugtem Zugriff zu schützen.

Schritt 4: Teste das Skript

Stelle sicher, dass du dein Skript testest, bevor du es speicherst. Klicke auf den Tab Testkontext auf der rechten Seite der Seite, um die simulierte Token-Payload und den Benutzerdatenkontext für Tests zu ändern.

Klicke auf Test ausführen in der rechten oberen Ecke des Editors, um das Skript mit den simulierten Daten auszuführen. Die Ausgabe des Skripts wird im Testergebnis-Bereich angezeigt.

hinweis:

Das Testergebnis ist die Ausgabe der Funktion getCustomJwtClaims mit den von dir festgelegten simulierten Daten ("zusätzliche Token-Ansprüche", die nach Abschluss von Schritt 3 im Sequenzdiagramm erhalten wurden). Die tatsächliche Token-Payload und der Benutzerdatenkontext werden unterschiedlich sein, wenn das Skript im Token-Ausstellungsprozess ausgeführt wird.

Klicke auf die Schaltfläche Erstellen, um das Skript zu speichern. Das benutzerdefinierte Token-Claims-Skript wird gespeichert und auf den Zugangstoken-Ausstellungsprozess angewendet.