Benutzer-Datenstruktur

Benutzer sind die Kerneinheiten im Identitätsdienst. In Logto umfassen sie grundlegende Authentifizierungsdaten basierend auf dem OpenID Connect-Protokoll sowie benutzerdefinierte Daten.

Benutzerprofil

Jeder Benutzer hat ein Profil, das alle Benutzerinformationen enthält.

Es besteht aus folgenden Datentypen:

Basisdaten: sind die Basisinformationen aus dem Benutzerprofil. Sie speichern alle anderen Benutzer-Eigenschaften außer sozialen identities und custom_data, wie Benutzer-ID, Benutzername, E-Mail, Telefonnummer und wann sich der Benutzer zuletzt angemeldet hat.
Soziale Identitäten: speichert die Benutzerinformationen, die durch Social Sign-in (d. h. Anmeldung mit einem Social Connector) abgerufen wurden, wie Facebook, GitHub und WeChat.
Benutzerdefinierte Daten: speichert zusätzliche Benutzerinformationen, die nicht in den vordefinierten Benutzereigenschaften aufgeführt sind, wie bevorzugte Farbe und Sprache des Benutzers.

Hier ist ein Beispiel für die Daten eines Benutzers, die durch eine Anmeldung bei Facebook abgerufen wurden:

{
  "id": "iHXPuSb9eMzt",
  "username": null,
  "primaryEmail": null,
  "primaryPhone": null,
  "name": "John Doe",
  "avatar": "https://example.com/avatar.png",
  "customData": {
    "preferences": {
      "language": "en",
      "color": "#f236c9"
    }
  },
  "identities": {
    "facebook": {
      "userId": "106077000000000",
      "details": {
        "id": "106077000000000",
        "name": "John Doe",
        "email": "[email protected]",
        "avatar": "https://example.com/avatar.png"
      }
    }
  },
  "lastSignInAt": 1655799453171,
  "applicationId": "admin_console"
}

Du kannst das Benutzerprofil über die Logto Console oder die Logto Management API abfragen, z. B. GET /api/users/:userId.

Basisdaten

Gehen wir alle Eigenschaften der Basisdaten eines Benutzers durch.

id

id ist ein eindeutig generierter Schlüssel zur Identifizierung des Benutzers in Logto.

username

username wird für die Anmeldung mit Benutzername und Passwort verwendet.

Der Wert stammt vom Benutzernamen, mit dem sich der Benutzer erstmals registriert hat. Er kann null sein. Ein nicht-null Wert darf maximal 128 Zeichen lang sein, nur Buchstaben, Zahlen und Unterstriche (_) enthalten und NICHT mit einer Zahl beginnen. Die Groß- und Kleinschreibung wird beachtet.

primary_email

primary_email ist die E-Mail-Adresse des Benutzers, die für die Anmeldung mit E-Mail und Passwort / Verifizierungscode verwendet wird.

Der Wert stammt in der Regel von der E-Mail-Adresse, mit der sich der Benutzer erstmals registriert hat. Er kann null sein. Die maximale Länge beträgt 128.

primary_phone

primary_phone ist die Telefonnummer des Benutzers, die für die Anmeldung mit Telefonnummer und Passwort / Verifizierungscode aus SMS verwendet wird.

Der Wert stammt in der Regel von der Telefonnummer, mit der sich der Benutzer erstmals registriert hat. Er kann null sein. Ein nicht-null Wert sollte Zahlen enthalten, die mit dem Ländervorwahl-Code (ohne das Pluszeichen +) beginnen.

name

name ist der vollständige Name des Benutzers. Die maximale Länge beträgt 128.

avatar

avatar ist die URL, die auf das Avatarbild des Benutzers zeigt. Die maximale Länge beträgt 2048.

Wenn sich der Benutzer mit einem Social Connector wie Google oder Facebook registriert, kann der Wert aus den sozialen Benutzerinformationen übernommen werden.

hinweis:

Diese Eigenschaft wird dem picture-Anspruch im OpenID Connect-Standard zugeordnet.

profile

profile speichert zusätzliche OpenID Connect Standardansprüche, die nicht in den Benutzereigenschaften enthalten sind.

Die Typdefinition findest du in dieser Datei. Hier eine Kopie der Typdefinition:

type UserProfile = Partial<{
  familyName: string;
  givenName: string;
  middleName: string;
  nickname: string;
  preferredUsername: string;
  profile: string;
  website: string;
  gender: string;
  birthdate: string;
  zoneinfo: string;
  locale: string;
  address: Partial<{
    formatted: string;
    streetAddress: string;
    locality: string;
    region: string;
    postalCode: string;
    country: string;
  }>;
}>;

hinweis:

Partial bedeutet, dass alle Eigenschaften optional sind.

Ein Unterschied zu anderen Standardansprüchen ist, dass die Eigenschaften in profile nur dann im ID-Token oder in der Antwort des userinfo-Endpunkts enthalten sind, wenn ihre Werte nicht leer sind, während andere Standardansprüche null zurückgeben, wenn die Werte leer sind.

application_id

Der Wert von application_id stammt von der Anwendung, bei der sich der Benutzer erstmals angemeldet hat. Er kann null sein.

last_sign_in_at

last_sign_in_at ist der Zeitstempel mit Zeitzone, wann sich der Benutzer zuletzt angemeldet hat.

created_at

created_at ist der Zeitstempel mit Zeitzone, wann der Benutzer das Konto registriert hat.

updated_at

updated_at ist der Zeitstempel mit Zeitzone, wann die Profilinformationen des Benutzers zuletzt aktualisiert wurden.

has_password

has_password ist ein boolescher Wert, der angibt, ob der Benutzer ein Passwort hat. Du kannst diesen Status anzeigen und verwalten, einschließlich Festlegen eines neuen oder Zurücksetzen des Passworts auf der Detailseite von Console > Benutzerverwaltung.

password_encrypted

password_encrypted wird verwendet, um das verschlüsselte Passwort des Benutzers zu speichern.

Der Wert stammt vom Passwort, mit dem sich der Benutzer erstmals registriert hat. Er kann null sein. Wenn der Wert nicht null ist, sollte der ursprüngliche Inhalt vor der Verschlüsselung mindestens sechs Zeichen lang sein.

password_encryption_method

password_encryption_method wird verwendet, um das Passwort des Benutzers zu verschlüsseln. Der Wert wird initialisiert, wenn sich der Benutzer mit Benutzername und Passwort registriert. Er kann null sein.

Logto verwendet standardmäßig die Argon2-Implementierung node-argon2 als Verschlüsselungsmethode; siehe die Referenz für Details, falls du interessiert bist.

Beispiel für password_encrypted und password_encryption_method von einem Benutzer, dessen Passwort 123456 ist:

{
  "password_encryption_method": "Argon2i",
  "password_encrypted": "$argon2i$v=19$m=4096,t=10,p=1$aZzrqpSX45DOo+9uEW6XVw$O4MdirF0mtuWWWz68eyNAt2u1FzzV3m3g00oIxmEr0U"
}

is_suspended

is_suspended ist ein boolescher Wert, der angibt, ob ein Benutzer gesperrt ist oder nicht. Der Wert kann durch Aufruf der Logto Management API oder über die Logto Console verwaltet werden.

Sobald ein Benutzer gesperrt ist, werden die zuvor gewährten Auffrischungstokens sofort widerrufen und der Benutzer kann sich nicht mehr bei Logto authentifizieren.

mfa_verification_factors

mfa_verification_factors ist ein Array, das die mit dem Benutzerkonto verknüpften Multi-Faktor-Authentifizierung (MFA)-Methoden auflistet. Mögliche Werte sind: Totp (Authenticator-App OTP), WebAuthn (Passkey) und BackupCode.

mfaVerificationFactors: ("Totp" | "WebAuthn" | "BackupCode")[];

identities enthält die durch Social Sign-in (d. h. Anmeldung mit einem Social Connector) abgerufenen Benutzerinformationen. Die identities jedes Benutzers werden in einem eigenen JSON-Objekt gespeichert.

Die Benutzerinformationen variieren je nach Anbieter sozialer Identitäten (d. h. soziales Netzwerk) und umfassen typischerweise Folgendes:

target des Identitätsanbieters, wie "facebook" oder "google"
Eindeutiger Benutzeridentifikator für diesen Anbieter
Name des Benutzers
Verifizierte E-Mail des Benutzers
Avatar des Benutzers

Das Benutzerkonto kann über Social Sign-in mit mehreren Anbietern sozialer Identitäten verknüpft sein; die entsprechenden Benutzerinformationen, die von diesen Anbietern abgerufen werden, werden im identities-Objekt gespeichert.

Beispiel für identities eines Benutzers, der sich sowohl mit Google als auch mit Facebook angemeldet hat:

{
  "facebook": {
    "userId": "5110888888888888",
    "details": {
      "id": "5110888888888888",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar": "https://example.com/avatar.png"
    }
  },
  "google": {
    "userId": "111000000000000000000",
    "details": {
      "id": "111000000000000000000",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar": "https://example.com/avatar.png"
    }
  }
}

SSO-Identitäten

sso_identities enthält die durch Enterprise SSO (d. h. Single Sign-On-Anmeldung mit einem Enterprise Connector](/connectors/enterprise-connectors)) abgerufenen Benutzerinformationen. Die ssoIdentities jedes Benutzers werden in einem eigenen JSON-Objekt gespeichert.

Die von der SSO-Identitätsquelle synchronisierten Daten hängen von den im Enterprise Connector konfigurierten Berechtigungen ab. Hier ist eine Kopie der TypeScript-Typdefinition:

type SSOIdentity = {
  issuer: string;
  identityId: string;
  detail: JsonObject; // Siehe https://github.com/withtyped/withtyped/blob/master/packages/server/src/types.ts#L12
};

Benutzerdefinierte Daten

custom_data speichert zusätzliche Benutzerinformationen, die nicht in den vordefinierten Benutzereigenschaften aufgeführt sind.

Du kannst custom_data für folgende Zwecke verwenden:

Erfassen, ob bestimmte Aktionen vom Benutzer durchgeführt wurden, z. B. ob die Willkommensseite gesehen wurde.
Anwendungsspezifische Daten im Benutzerprofil speichern, z. B. bevorzugte Sprache und Erscheinungsbild des Benutzers pro Anwendung.
Andere beliebige, benutzerbezogene Daten pflegen.

Beispiel für custom_data eines Admin-Benutzers in Logto:

{
  "adminConsolePreferences": {
    "language": "en",
    "appearanceMode": "system",
    "experienceNoticeConfirmed": true
  },
  "customDataFoo": {
    "foo": "foo"
  },
  "customDataBar": {
    "bar": "bar"
  }
}

Das custom_data jedes Benutzers wird in einem eigenen JSON-Objekt gespeichert.

hinweis:

Lege KEINE sensiblen Daten in custom_data ab.

Benutzerdefinierte Daten können nach der Benutzeranmeldung über benutzerdefinierte JWT-Token-Ansprüche abgerufen werden, und JWT-Tokens sind base64-codiert (nicht verschlüsselt) und werden häufig über Netzwerke übertragen, wodurch sensible Daten leicht offengelegt werden können.

Du kannst ein Benutzerprofil mit custom_data über die Management API abrufen und an Frontend-Apps oder externe Backend-Dienste senden. Daher kann das Ablegen sensibler Informationen in custom_data zu Datenlecks führen.

Wenn du dennoch sensible Informationen in custom_data speichern möchtest, empfehlen wir, diese zuerst zu verschlüsseln. Verschlüssele/entschlüssele sie nur in einer vertrauenswürdigen Instanz wie deinen Backend-Diensten und vermeide dies in Frontend-Apps. Dadurch wird der Schaden minimiert, falls die custom_data deiner Benutzer versehentlich offengelegt wird.

So sammelst und aktualisierst du benutzerdefinierte Daten

Verwende die Funktion Benutzerprofil erfassen, um benutzerdefinierte Daten während der Benutzerregistrierung zu sammeln.
Verwende die Account API, um Endbenutzerprofil- oder Kontoeinstellungen zu implementieren.
- Verwende GET /api/my-account, um alle Benutzerdaten abzurufen.
- Verwende PATCH /api/my-account, um die custom_data eines Benutzers zu aktualisieren.
Verwende die Management API für Benutzerverwaltung oder erweiterte benutzerdefinierte Abläufe:
- Verwende GET /api/users/{userId}, um alle Benutzerdaten abzurufen.
- Verwende PATCH /api/users/{userId}/custom-data, um die custom_data eines Benutzers zu aktualisieren.
Dein Support-Team kann die custom_data eines Benutzers direkt in Console > Benutzerverwaltung aktualisieren. Erfahre mehr über das Anzeigen und Aktualisieren von Benutzerprofilen.

Sei vorsichtig beim Aktualisieren. Das Aktualisieren der custom_data eines Benutzers überschreibt den ursprünglichen Inhalt im Speicher vollständig.

Wenn dein Eingabewert beim Aufruf der Update-custom_data-API wie folgt aussieht (angenommen, die ursprünglichen custom_data sind die zuvor gezeigten Beispieldaten):

{
  "customDataBaz": {
    "baz": "baz"
  }
}

dann sieht der neue custom_data-Wert nach dem Update so aus:

{
  "customDataBaz": {
    "baz": "baz"
  }
}

Das heißt, der aktualisierte Feldwert hat nichts mehr mit dem vorherigen Wert zu tun.

Eigenschaftsreferenz

Die folgenden Spalten der Benutzer-DB-Tabelle (außer password_encrypted und password_encryption_method) sind im Benutzerprofil sichtbar, was bedeutet, dass du sie über die Management API abfragen kannst.

Name	Typ	Beschreibung	Eindeutig	Erforderlich
id	string	Eindeutiger Identifikator	✅	✅
username	string	Benutzername für Anmeldung	✅	❌
primary_email	string	Primäre E-Mail	✅	❌
primary_phone	string	Primäre Telefonnummer	✅	❌
name	string	Vollständiger Name	❌	❌
avatar	string	URL zum Avatarbild des Benutzers	❌	❌
profile	object	Benutzerprofil	❌	✅
identities	object	Durch Social Sign-in abgerufene Benutzerinfos	❌	✅
custom_data	object	Zusätzliche Infos in anpassbaren Feldern	❌	✅
application_id	string	Anwendungs-ID, bei der sich der Benutzer zuerst registriert hat	❌	✅
last_sign_in_at	date time	Zeitstempel der letzten Anmeldung	❌	✅
password_encrypted	string	Verschlüsseltes Passwort	❌	❌
password_encryption_method	string	Passwort-Verschlüsselungsmethode	❌	❌
is_suspended	bool	Benutzer-Sperrmarkierung	❌	✅
mfa_verifications	object[]	MFA-Verifizierungsfaktoren	❌	✅

Eindeutig: Stellt die Eindeutigkeit der in eine Eigenschaft einer Datenbanktabelle eingegebenen Werte sicher.
Erforderlich: Stellt sicher, dass die in eine Eigenschaft einer Datenbanktabelle eingegebenen Werte NICHT null sein können.

Sicheres Zentrum für Benutzerdaten in Bewegung

Benutzerprofil​

Basisdaten​

id​

username​

primary_email​

primary_phone​

name​

avatar​

profile​

application_id​

last_sign_in_at​

created_at​

updated_at​

has_password​

password_encrypted​

password_encryption_method​

is_suspended​

mfa_verification_factors​

Soziale Identitäten​

SSO-Identitäten​

Benutzerdefinierte Daten​

Eigenschaftsreferenz​

Verwandte Ressourcen​

Benutzerprofil

Basisdaten

id

username

primary_email

primary_phone

name

avatar

profile

application_id

last_sign_in_at

created_at

updated_at

has_password

password_encrypted

password_encryption_method

is_suspended

mfa_verification_factors

Soziale Identitäten

SSO-Identitäten

Benutzerdefinierte Daten

Eigenschaftsreferenz

Verwandte Ressourcen