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 den folgenden Datentypen:

Basisdaten: sind die Basisinformationen aus dem Benutzerprofil. Sie speichern alle anderen Eigenschaften des Benutzers, außer den 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 die soziale Anmeldung (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": "johndoe@logto.io",
        "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 eindeutiger, automatisch 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 zuerst registriert hat. Er kann null sein. Sein 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 zuerst registriert hat. Er kann null sein. Die maximale Länge beträgt 128.

Nur verifizierte E-Mail-Adressen von sozialen oder Enterprise SSO Identitätsanbietern können synchronisiert und als primary_email gespeichert werden.

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 zuerst registriert hat. Er kann null sein. Sein nicht-null Wert sollte Zahlen enthalten, die mit dem Ländervorwahl-Code (ohne das Pluszeichen +) beginnen.

Nur verifizierte Telefonnummern von sozialen oder Enterprise SSO Identitätsanbietern können synchronisiert und als primary_phone gespeichert werden.

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 abgerufen werden.

hinweis:

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

profile

profile speichert zusätzliche OpenID Connect Standard-Claims, die nicht in den Benutzereigenschaften enthalten sind.

Die Typdefinition findest du in dieser Datei. Hier ist 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 den anderen Standard-Claims besteht darin, 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 Standard-Claims null zurückgeben, wenn die Werte leer sind.

application_id

Der Wert von application_id stammt von der Anwendung, bei der sich der Benutzer zuerst 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 des Setzens eines neuen oder Zurücksetzens 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 zuerst 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 beim Registrieren mit Benutzername und Passwort initialisiert. 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 eines Benutzers, 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 soziale Anmeldung (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 der sozialen Identität (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 mit mehreren sozialen Identitätsanbietern über soziale Anmeldung 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": "johndoe@logto.io",
      "avatar": "https://example.com/avatar.png"
    }
  },
  "google": {
    "userId": "111000000000000000000",
    "details": {
      "id": "111000000000000000000",
      "name": "John Doe",
      "email": "johndoe@gmail.com",
      "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 dem SSO-Identitätsanbieter 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:

Festhalten, ob bestimmte Aktionen vom Benutzer durchgeführt wurden, z. B. ob die Willkommensseite gesehen wurde.
Anwendungsspezifische Daten im Benutzerprofil speichern, wie die bevorzugte Sprache und das 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-Services 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 vorher zu verschlüsseln. Verschlüssele/entschlüssele sie nur in einer vertrauenswürdigen Instanz wie deinen Backend-Services und vermeide dies in den Frontend-Apps. Dadurch wird der Schaden minimiert, falls die custom_data deiner Benutzer versehentlich offengelegt wird.

Wie man benutzerdefinierte Benutzerdaten sammelt und aktualisiert

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 die Benutzerverwaltung oder fortgeschrittene 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 Aktualisieren so aus:

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

Das heißt, der aktualisierte Feldwert hat nichts 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 soziale Anmeldung abgerufene Daten	❌	✅
custom_data	object	Zusätzliche Infos in anpassbaren Eigenschaften	❌	✅
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 unterwegs

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