使用者資料結構

使用者是身分服務的核心實體。在 Logto 中，他們包含基於 OpenID Connect 協議的基本驗證 (Authentication) 資料，以及自訂資料。

使用者檔案

每位使用者都有一個包含所有使用者資訊的檔案。

它由以下類型的資料組成：

基本資料：來自使用者檔案的基本資訊。它儲存所有其他 user 的屬性，除了社交 identities 和 custom_data，例如使用者 ID、使用者名稱、電子郵件、電話號碼以及使用者上次登入的時間。
社交身分：儲存從社交登入（即使用社交連接器登入）獲取的使用者資訊，例如 Facebook、GitHub 和 WeChat。
自訂資料：儲存未列在預定義使用者屬性中的其他使用者資訊，例如使用者偏好的顏色和語言。

以下是一個從 Facebook 登入獲取的使用者資料範例：

{
  "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"
}

你可以使用 Logto Console 或 Logto Management API 查詢使用者檔案，例如 GET /api/users/:userId。

基本資料

讓我們逐步了解使用者 基本資料 中的所有屬性。

id

id 是在 Logto 中識別使用者的唯一自動生成鍵。

username

username 用於使用 username 和密碼登入。

其值來自使用者首次註冊時的使用者名稱。它可能為 null。其非空值不應超過 128 個字元，只能包含字母、數字和底線 (_)，且不能以數字開頭。區分大小寫。

primary_email

primary_email 是使用者的電子郵件地址，用於使用電子郵件和密碼 / 驗證碼登入。

其值通常來自使用者首次註冊時的電子郵件地址。它可能為 null。其最大長度為 128。

primary_phone

primary_phone 是使用者的電話號碼，用於使用電話號碼和密碼 / 簡訊驗證碼登入。

其值通常來自使用者首次註冊時的電話號碼。它可能為 null。其非空值應包含以國家區碼（不含加號 +）為前綴的數字。

name

name 是使用者的全名。其最大長度為 128。

avatar

avatar 是指向使用者頭像圖片的 URL。其最大長度為 2048。

如果使用者使用像 Google 和 Facebook 這樣的社交連接器註冊，其值可能會從社交使用者資訊中獲取。

備註:

此屬性映射到 OpenID Connect 標準中的 picture 宣告 (Claim)。

profile

profile 儲存未包含在使用者屬性中的其他 OpenID Connect 標準宣告 (Claims)。

其類型定義可在此檔案中找到。以下是類型定義的副本：

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;
  }>;
}>;

備註:

Partial 表示所有屬性都是可選的。

與其他標準宣告 (Claims) 的不同之處在於，profile 中的屬性只有在其值不為空時才會包含在 ID 權杖 (ID token) 或使用者資訊端點響應中，而其他標準宣告 (Claims) 如果值為空則會返回 null。

application_id

application_id 的值來自使用者首次登入的應用程式。它可能為 null。

last_sign_in_at

last_sign_in_at 是使用者上次登入時的時間戳，包含時區。

created_at

created_at 是使用者註冊帳戶時的時間戳，包含時區。

updated_at

updated_at 是使用者檔案資訊最後更新時的時間戳，包含時區。

has_password

has_password 是一個布林值，表示使用者是否有密碼。你可以在 Console > User management 的詳細頁面查看和管理此狀態，包括設定新密碼或重設密碼。

password_encrypted

password_encrypted 用於儲存使用者的加密密碼。

其值來自使用者首次註冊時的密碼。它可能為 null。如果其值為非空，則加密前的原始內容應至少為六個字元。

password_encryption_method

password_encryption_method 用於加密使用者的密碼。其值在使用者註冊時使用使用者名稱和密碼初始化。它可能為 null。

Logto 預設使用 Argon2 的實現 node-argon2 作為加密方法；如果你有興趣，請參閱參考資料以獲取詳細資訊。

從一個密碼為 123456 的使用者中取樣的 password_encrypted 和 password_encryption_method：

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

is_suspended

is_suspended 是一個布林值，表示使用者是否被停用。該值可以通過調用 Logto Management API 或使用 Logto Console 進行管理。

一旦使用者被停用，預先授予的重新整理權杖 (Refresh tokens) 將立即被撤銷，使用者將無法再通過 Logto 進行驗證 (Authentication)。

mfa_verification_factors

mfa_verification_factors 是一個列出與使用者帳戶相關的多重要素驗證 (MFA, Multi-factor authentication) 方法的陣列。可能的值包括：Totp（驗證器應用程式 OTP）、WebAuthn（Passkey）和 BackupCode。

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

identities 包含從社交登入（即使用社交連接器登入）獲取的使用者資訊。每位使用者的 identities 都儲存在一個單獨的 JSON 物件中。

使用者資訊因社交身分提供者（即社交網路平台）而異，通常包括以下內容：

身分提供者的 target，例如 "facebook" 或 "google"
該提供者的使用者唯一識別碼
使用者名稱
使用者已驗證的電子郵件
使用者頭像

使用者的帳戶可能通過社交登入連結到多個社交身分提供者；從這些提供者獲取的相應使用者資訊將儲存在 identities 物件中。

從一個同時使用 Google 和 Facebook 登入的使用者中取樣的 identities：

{
  "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 身分

sso_identities 包含從企業級單一登入 (Enterprise SSO)（即使用企業連接器進行單一登入 (SSO) 登入](/connectors/enterprise-connectors)）獲取的使用者資訊。每位使用者的 ssoIdentities 都儲存在一個單獨的 JSON 物件中。

從 SSO 身分提供者同步的資料取決於企業連接器中配置的權限範圍 (Scopes)。以下是 TypeScript 類型定義的副本：

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

自訂資料

custom_data 儲存未列在預定義使用者屬性中的其他使用者資訊。

你可以使用 custom_data 來執行以下操作：

記錄使用者是否已完成特定操作，例如是否已查看歡迎頁面。
在使用者檔案中儲存應用程式特定的資料，例如使用者每個應用程式的偏好語言和外觀。
維護與使用者相關的其他任意資料。

從 Logto 中的一位管理使用者中取樣的 custom_data：

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

每位使用者的 custom_data 都儲存在一個單獨的 JSON 物件中。

注意：請勿將敏感資料放入 custom_data。

你可以使用 Management API 獲取包含 custom_data 的使用者檔案，並將其發送到前端應用程式或外部後端服務。因此，將敏感資訊放入 custom_data 可能會導致資料洩漏。

如果你仍然希望將敏感資訊放入 custom_data，我們建議先對其進行加密。僅在受信任的方（如你的後端服務）中進行加密 / 解密，避免在前端應用程式中進行。這將最大限度地減少如果你的使用者的 custom_data 被意外洩漏時的損失。

你可以使用 Logto Console 或 Logto Management API 更新使用者的 custom_data，例如 PATCH /api/users/:userId。

謹慎更新

更新使用者的 custom_data 將完全覆蓋其在儲存中的原始內容。

例如，如果你調用更新 custom_data API 的輸入看起來像這樣（假設原始 custom_data 是先前顯示的範例資料）：

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

那麼更新後的新 custom_data 值應為：

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

也就是說，更新後的欄位值與之前的值無關。

屬性參考

以下資料庫使用者表格欄位（除了 password_encrypted 和 password_encryption_method）在使用者檔案中可見，這意味著你可以使用 Management API 查詢它們。

名稱	類型	描述	唯一性	必需
id	string	唯一識別碼	✅	✅
username	string	用於登入的使用者名稱	✅	❌
primary_email	string	主要電子郵件	✅	❌
primary_phone	string	主要電話號碼	✅	❌
name	string	全名	❌	❌
avatar	string	指向使用者頭像圖片的 URL	❌	❌
profile	object	使用者檔案	❌	✅
identities	object	從社交登入獲取的使用者資訊	❌	✅
custom_data	object	自訂屬性中的其他資訊	❌	✅
application_id	string	使用者首次註冊的應用程式 ID	❌	✅
last_sign_in_at	date time	使用者上次登入時的時間戳	❌	✅
password_encrypted	string	加密密碼	❌	❌
password_encryption_method	string	密碼加密方法	❌	❌
is_suspended	bool	使用者停用標記	❌	✅
mfa_verifications	object[]	MFA 驗證因素	❌	✅

唯一性：確保輸入到資料庫表格屬性中的值的唯一性。
必需：確保輸入到資料庫表格屬性中的值不能為 null。

移動中的使用者資料安全中心

使用者檔案​

基本資料​

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​

社交身分​

SSO 身分​

自訂資料​

屬性參考​

相關資源​