ユーザーデータ構造

ユーザーはアイデンティティサービスの中核的なエンティティです。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": "[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 はユーザーの電話番号で、電話番号と SMS からのパスワード / 認証コードでサインインするために使用されます。

その値は通常、ユーザーが最初に登録した電話番号から取得されます。null の場合があります。非 null の値は、国際電話番号の国番号（プラス記号 + を除く）で始まる数字を含む必要があります。

name

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

avatar

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

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

注記:

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

profile

profile は、ユーザーのプロパティに含まれていない追加の OpenID Connect 標準クレームを保存します。

その型定義はこのファイルで見つけることができます。以下は型定義のコピーです：

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 トークンまたは 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 > User management の詳細ページで新しいパスワードの設定やリセットを含めて表示および管理できます。

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 (Authenticator アプリの 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 は、エンタープライズシングルサインオン (SSO)（つまり、エンタープライズコネクターを使用したシングルサインオンログイン](/connectors/enterprise-connectors)）から取得したユーザー情報を含みます。各ユーザーの 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 に機密データを入れないでください。

custom_data を含むユーザープロフィールを Management API を使用して取得し、フロントエンドアプリや外部バックエンドサービスに送信することができます。したがって、custom_data に機密情報を入れるとデータ漏洩の原因になる可能性があります。

それでも custom_data に機密情報を入れたい場合は、まず暗号化することをお勧めします。信頼できるパーティ（例えばバックエンドサービス）でのみ暗号化 / 復号化を行い、フロントエンドアプリでは避けてください。これにより、ユーザーの custom_data が誤って漏洩した場合の損失を最小限に抑えることができます。

ユーザーの custom_data は Logto Console または Logto Management API を使用して更新できます。例えば、PATCH /api/users/:userId です。

慎重に更新してください

ユーザーの 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 でないことを保証します。

ユーザーデータの移動のための安全なハブ

ユーザープロフィール​

基本データ​

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 アイデンティティ​

カスタムデータ​

プロパティリファレンス​

関連リソース​