ユーザーデータ構造

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

ユーザープロフィール

各ユーザーには、すべてのユーザー情報 を含むプロフィールがあります。

以下の種類のデータで構成されています：

• 基本データ：ユーザープロフィールからの基本情報です。ユーザー ID、ユーザー名、メールアドレス、電話番号、ユーザーが最後にサインインした日時など、ソーシャル identities や custom_data を除くすべての ユーザー のプロパティを保存します。
• ソーシャルアイデンティティ：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_signed_in_at

last_signed_in_at は、ユーザーが最後にサインインしたときのタイムゾーン付きのタイムスタンプです。

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) されることができなくなります。

プロパティリファレンス

次のプロパティ（password_encrypted と password_encryption_method を除く）はユーザープロフィールに表示されます。つまり、Management API を使用してクエリできます。

名前	型	説明	一意	必須
id	string	一意の識別子	✅	✅
username	string	サインイン用のユーザー名	✅	❌
primary_email	string	プライマリメール	✅	❌
primary_phone	string	プライマリ電話番号	✅	❌
name	string	フルネーム	❌	❌
avatar	string	ユーザーのアバター画像を指す URL	❌	❌
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	ユーザー停止マーク	❌	✅

• 一意: データベーステーブルのプロパティに入力された値の一意性を保証します。
• 必須: データベーステーブルのプロパティに入力された値が null でないことを保証します。

ソーシャルアイデンティティ

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

カスタムデータ

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

つまり、更新されたフィールドの値は以前の値とは関係ありません。

関連リソース

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