ユーザーデータ構造
ユーザーはアイデンティティサービスの中核となるエンティティです。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 コンソール または Logto Management API(例: GET /api/users/:userId
)で取得できます。
基本データ
ユーザーの 基本データ に含まれるすべてのプロパティを見ていきましょう。
id
id は Logto 内でユーザーを識別するための一意な自動生成キーです。
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
クレーム (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
を返します。
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 は、ユーザーがパスワードを持っているかどうかを示すブール値です。コンソール > ユーザー管理 の詳細ページでこの状態の確認や新規設定・リセットが可能です。
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 コンソールで管理できます。
ユーザーが停止されると、事前に付与されたリフレッシュ トークン (Refresh token) は即座に失効し、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": "[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)(エンタープライズコネクターによるシングルサインオン)から取得したユーザー情報が含まれます。各ユーザーの 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 が漏洩した場合の損失を最小限に抑えられます。
ユーザーカスタムデータの収集と更新方法
- ユーザープロファイルの収集 機能を使って、ユーザーサインアップ時にカスタムデータを収集できます。
- 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 を更新
- サポートチームは コンソール > ユーザー管理 で直接ユーザーの 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
であってはならないことを保証します。
関連リソース
ユーザーデータ移動のためのセキュアハブ