メインコンテンツまでスキップ

ユーザーデータ構造

ユーザーはアイデンティティサービスの中核となるエンティティです。Logto では、 OpenID Connect プロトコルに基づく基本的な認証 (Authentication) データとカスタムデータを含みます。

ユーザープロファイル​

各ユーザーは すべてのユーザー情報 を含むプロファイルを持っています。

プロファイルは以下の種類のデータで構成されています：

  • 基本データ：ユーザープロファイルからの基本情報です。ソーシャル 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": "johndoe@logto.io",
        "avatar": "https://example.com/avatar.png"
      }
    }
  },
  "lastSignInAt": 1655799453171,
  "applicationId": "admin_console"
}

ユーザープロファイルは Logto Console または Logto Management API（例： GET /api/users/:userId）で取得できます。

基本データ​

ユーザーの 基本データ に含まれるすべてのプロパティを見ていきましょう。

id​

id は Logto 内でユーザーを一意に識別するキーです。デフォルトで自動生成されます。セルフホスト型 Logto では、Management API を使ってユーザー作成時にカスタム id を指定できます（例： 移行時に既存ユーザー ID を保持する など）。

username​

username は username とパスワードでサインインする際に使用されます。

値はユーザーが最初に登録したユーザー名です。null の場合もあります。非 null の場合、128 文字以内で、英数字とアンダースコア（_）のみを含み、数字で始まってはいけません。デフォルトで大文字小文字を区別します。これらのルールは ユーザー名ポリシー でテナントごとにさらに制限できます。

primary_email​

primary_email はユーザーのメールアドレスで、メールアドレスとパスワード / 認証コードでサインインする際に使用されます。

値は通常、ユーザーが最初に登録したメールアドレスです。null の場合もあります。最大長は 128 です。

ソーシャルまたはエンタープライズ SSO アイデンティティプロバイダーからの認証済みメールアドレスのみが primary_email として同期・保存されます。

primary_phone​

primary_phone はユーザーの電話番号で、電話番号とパスワード / SMS の認証コードでサインインする際に使用されます。

値は通常、ユーザーが最初に登録した電話番号です。null の場合もあります。非 null の場合、 国番号（プラス記号 + を除く）を先頭に付けた数字のみを含みます。

ソーシャルまたはエンタープライズ SSO アイデンティティプロバイダーからの認証済み電話番号のみが primary_phone として同期・保存されます。

name​

name はユーザーのフルネームです。最大長は 128 です。

avatar​

avatar はユーザーのアバター画像の URL です。最大長は 2048 です。

Google や Facebook などのソーシャルコネクターで登録した場合、この値はソーシャルユーザー情報から取得されることがあります。

注記:

このプロパティは OpenID Connect 標準の picture クレーム (Claim) にマッピングされます。

profile​

profile には、ユーザーのプロパティに含まれていない OpenID Connect 標準クレーム (Claim) の追加情報が格納されます。

型定義は こちらのファイル で確認できます。以下は型定義の抜粋です：

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 はすべてのプロパティが任意であることを意味します。

他の標準クレーム (Claim) との違いは、profile 内のプロパティは値が空でない場合のみ ID トークン または userinfo エンドポイントのレスポンスに含まれる点です。他の標準クレーム (Claim) は値が空の場合 null を返します。

例外として preferred_username クレーム (Claim) があります：profile の preferredUsername が空の場合、このクレーム (Claim) はユーザーの username にフォールバックします。これにより、標準準拠のクライアントはすぐに利用可能な値を受け取れます。明示的な preferredUsername の値が設定されている場合はそちらが優先されます。

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 の場合、暗号化前の元の内容は 6 文字以上である必要があります。

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 で管理できます。

ユーザーが停止されると、事前に付与されたリフレッシュトークンは即座に失効し、Logto で認証 (Authentication) できなくなります。

mfa_verification_factors​

mfa_verification_factors は、ユーザーアカウントに紐づく 多要素認証 (MFA) の方式を列挙した配列です。値には Totp（認証アプリ OTP）、WebAuthn（パスキー）、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": "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 アイデンティティ​

sso_identities には、 エンタープライズシングルサインオン (SSO)（エンタープライズコネクター でのシングルサインオン）から取得したユーザー情報が格納されます。各ユーザーの ssoIdentities は個別の JSON オブジェクトとして保存されます。

SSO アイデンティティプロバイダーから同期されるデータは、エンタープライズコネクターで設定されたスコープに依存します。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 に機密データを入れないでください。

カスタムデータはユーザーサインイン後に カスタム JWT トークンクレーム (Claim) を通じてアクセスできますが、JWT トークンは base64 エンコード（暗号化ではありません）され、ネットワーク上で頻繁に送信されるため、機密データが簡単に漏洩します。

Management API で custom_data を含むユーザープロファイルを取得し、フロントエンドアプリや外部バックエンドサービスに送信することもできます。そのため、custom_data に機密情報を入れるとデータ漏洩の原因となります。

それでも custom_data に機密情報を入れたい場合は、事前に暗号化することを推奨します。暗号化 / 復号は信頼できるバックエンドサービスなどでのみ行い、フロントエンドアプリでは避けてください。これにより、万が一 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 で取得できます。

名前型説明一意必須
idstring一意識別子✅✅
usernamestringサインイン用ユーザー名✅❌
primary_emailstringプライマリメールアドレス✅❌
primary_phonestringプライマリ電話番号✅❌
namestringフルネーム❌❌
avatarstringユーザーのアバター画像の URL❌❌
profileobjectユーザープロファイル❌✅
identitiesobjectソーシャルサインインから取得したユーザー情報❌✅
custom_dataobjectカスタマイズ可能な追加情報❌✅
application_idstringユーザーが最初に登録したアプリケーション ID❌✅
last_sign_in_atdate time最終サインイン日時❌✅
password_encryptedstring暗号化されたパスワード❌❌
password_encryption_methodstringパスワード暗号化方式❌❌
is_suspendedboolユーザー停止マーク❌✅
mfa_verificationsobject[]MFA 検証要素❌✅
  • 一意：データベーステーブルのプロパティに入力された値の 一意性 を保証します。
  • 必須：データベーステーブルのプロパティに入力された値が null であってはならないことを保証します。
ユーザーデータ移動時のセキュアハブ