使用者資料結構

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

使用者檔案

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

其內容包含以下類型的資料：

• 基本資料：來自使用者檔案的基本資訊。儲存除了社交 identities 與 custom_data 以外的所有 user 屬性，例如使用者 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。非 null 值最長 128 字元，只能包含字母、數字與底線（_），且不得以數字開頭。區分大小寫。

primary_email

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

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

primary_phone

primary_phone 是使用者的手機號碼，用於以手機號碼與密碼 / 簡訊驗證碼登入。

其值通常來自使用者首次註冊時填寫的手機號碼。可能為 null。非 null 值應包含以國碼（不含加號 +）開頭的數字。

name

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

avatar

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

若使用者透過 Google、Facebook 等社交連接器註冊，該值可能來自社交平台的使用者資訊。

備註:

此屬性對應 OpenID Connect 標準中的 picture 宣告 (Claim)。

profile

profile 儲存額外的 OpenID Connect 標準宣告 (Standard 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 代表所有屬性皆為選填。

與其他標準宣告不同，profile 內的屬性僅在其值非空時才會包含於 ID 權杖 (ID token) 或 userinfo 端點回應中，而其他標準宣告若值為空則會回傳 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 > 使用者管理 詳細頁面檢視與管理此狀態，包括設定新密碼或重設密碼。

password_encrypted

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

其值來自使用者首次註冊時填寫的密碼。可能為 null。若非 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 驗證。

mfa_verification_factors

mfa_verification_factors 是一個陣列，列出與使用者帳號關聯的多重要素驗證 (MFA, Multi-factor authentication) 方法。可能值包括：Totp（驗證器 App 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, Single Sign-On)](/connectors/enterprise-connectors)）取得的使用者資訊。每個使用者的 ssoIdentities 以獨立 JSON 物件儲存。

從 SSO 身分提供者同步的資料取決於企業連接器設定的權限範圍 (Scopes)。以下為 TypeScript 型別定義：

type SSOIdentity = {
  issuer: string;
  identityId: string;
  detail: JsonObject; // 參見 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。

自訂資料可透過自訂 JWT 權杖宣告 (Custom JWT token claims) 在使用者登入後取得，而 JWT 權杖僅以 base64 編碼（非加密）並經常在網路間傳輸，任何敏感資料都容易外洩。

你也可能透過 Management API 取得包含 custom_data 的使用者檔案，並傳送給前端應用程式或外部後端服務。因此，將敏感資訊放入 custom_data 可能導致資料外洩。

若你仍需將敏感資訊放入 custom_data，建議先加密，且僅在可信任的後端服務進行加解密，避免於前端應用程式處理。如此可將 custom_data 外洩時的損失降至最低。

如何收集與更新使用者自訂資料

• 使用 收集使用者檔案 功能於註冊時收集自訂資料。
• 使用 Account API 實作終端使用者檔案或帳號設定。
  • 透過 GET /api/my-account 取得所有使用者資料。
  • 透過 PATCH /api/my-account 更新使用者 custom_data。
• 使用 Management API 進行使用者管理或進階自訂流程：
  • 透過 GET /api/users/{userId} 取得所有使用者資料。
  • 透過 PATCH /api/users/{userId}/custom-data 更新使用者 custom_data。
• 你的支援團隊可直接於 Console > 使用者管理 更新使用者 custom_data。詳情請參閱檢視與更新使用者檔案。

請謹慎操作。更新使用者 custom_data 會完全覆蓋原有內容。

例如，若你呼叫更新 custom_data API 時的輸入如下（假設原本的 custom_data 如前述範例）：

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

則更新後的新 custom_data 值為：

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

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

屬性參考

下列 DB 使用者資料表欄位（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。

相關資源

使用者資料流動的安全樞紐