初回要素認証後の検証 (Post first-factor verification)
初回要素認証後の検証 (Post first-factor verification) アクションは、レガシーパスワードシステムからのジャストインタイムユーザー移行をサポートします。
名前に反して、このアクションはすべての初回要素認証成功後に実行されるわけではありません。以下のすべての条件を満たす場合のみ実行されます:
- 体験 API (Experience API) のインタラクションが
SignInである。 - ユーザーがユーザー名、メールアドレス、または電話番号とパスワードを送信した。
- Logto のローカルパスワード認証 (Authentication) が失敗した。
- 識別子が既存の Logto ユーザーに属している場合、そのユーザーが停止されていない。
ローカルパスワードが有効な場合、Logto はアクションを実行せずに処理を続行します。登録、パスワード忘れ、非パスワードサインイン、停止ユーザーによる試行ではトリガーされません。
イベントペイロード
event の構造は次の通りです:
type PostFirstFactorVerificationEvent = {
// 機能名が Actions に変更された後も後方互換性のため保持。
key: 'inlineHook.postFirstFactorVerification';
interactionEvent: 'SignIn';
verificationType: 'Password';
identifier: {
type: 'username' | 'email' | 'phone';
value: string;
};
user: {
id: string;
username: string | null;
primaryEmail: string | null;
primaryPhone: string | null;
name: string | null;
avatar: string | null;
customData: Record<string, unknown>;
profile: Record<string, unknown>;
} | null;
password: string;
};
user は、識別子が Logto ユーザーに属していない場合は null です。それ以外の場合は、既存ユーザーの編集可能なプロフィールコンテキストが含まれます。
event.password はユーザーが送信した平文パスワードです。信頼できるレガシー認証 (Authentication) エンドポイントにのみ HTTPS 経由で送信してください。絶対にログに記録したり、保存したり、customData に格納したり、エラーに含めたり、アクションから返したりしないでください。
結果
レガシーシステムが送信された認証情報を検証した後、次のいずれかの結果を返します:
type ActionMfaVerification =
| {
type: 'Totp';
secret: string;
}
| {
type: 'BackupCode';
codes: string[];
}
| {
type: 'WebAuthn';
credentialId: string;
publicKey: string;
counter: number;
transports?: ('usb' | 'nfc' | 'ble' | 'internal' | 'cable' | 'hybrid' | 'smart-card')[];
agent?: string;
name?: string;
};
type PostFirstFactorVerificationResult =
| {
action: 'createUser';
passwordVerified: true;
user: ActionUserPatch;
mfaVerifications?: ActionMfaVerification[];
}
| {
action: 'updateUser';
passwordVerified: true;
user: ActionUserPatch;
mfaVerifications?: ActionMfaVerification[];
};
結果はイベントと一致している必要があります:
event.userがnullの場合はcreateUserを返します。event.userが存在する場合はupdateUserを返します。passwordVerifiedはリテラル値trueでなければなりません。userには サポートされているユーザーパッチフィールド のみを含めることができます。
新規ユーザーの場合、結果にサインイン識別子が含まれていなければ、Logto が送信された識別子を追加します。アクションで送信された識別子を別の値に変更することはできません。メールアドレスの比較は大文字小文字を区別せず、電話番号は正規化後に比較され、ユーザー名は完全一致が必要です。
結果が受け入れられると、Logto は送信されたパスワードを Argon2i でハッシュ化し、ユーザーのローカルパスワードとして保存します。スクリプトでパスワードハッシュを生成または返してはいけません。
レガシーシステムが認証情報を拒否した場合は undefined を返します。空、形式不正、またはサポートされていない結果も無効な認証情報として扱われます。
MFA 要素の移行
mfaVerifications を含めることで、ユーザーの既存の MFA 要素をパスワードとともに引き継ぐことができます。Logto は要素をユーザーの既存要素に追加し、アカウントで MFA を有効にします。そのため、MFA が必要な場合、同じサインインで移行された要素のいずれかによる認証が求められます。要素タイプはサインイン体験の MFA 設定で有効化されている必要があります。ユーザーまたは管理者がすでにアカウントに設定した skipMfaOnSignIn 設定は保持されます。
- TOTP —
{ type: 'Totp', secret }。secretは Base32 の TOTP シークレットです。Logto は空白を削除し、大文字に変換し、Base32 パディングを追加してから検証します。結果は 16~32 文字でなければなりません。ユーザーは TOTP 要素を 1 つだけ持てます。 - バックアップコード —
{ type: 'BackupCode', codes }。codesには 1~10 個のコードを含め、各コードは0-9およびa-fの 10 文字です。移行されたコードは未使用として保存されるため、レガシーシステムでまだ未使用のコードのみ渡してください。バックアップコードだけを唯一の要素にすることはできません:ユーザーはすでに他の要素を持っているか、同じ結果で新たに受け取る必要があります。 - WebAuthn —
{ type: 'WebAuthn', credentialId, publicKey, counter, transports?, agent?, name? }。credentialIdとpublicKeyはパディングなしの Base64URL 文字列です。publicKeyはクレデンシャルの公開鍵です。ユーザーが Logto にサインインするドメインで登録されたクレデンシャルのみ検証できるため、異なるドメインで登録されたパスキーは移行しないでください。
ユーザーがすでに持っている要素と同一の要素はスキップされます:同じ TOTP シークレット、同じ credentialId と publicKey の WebAuthn クレデンシャル、またはすでにユーザーセットに含まれている(使用済みかどうかに関わらず)バックアップコードです。以前に使用されたコードは使用済みのままです。
競合する要素は、既存の要素を置き換えるのではなく、エラーでサインインを失敗させます。これは、ユーザーがすでに TOTP を持っている場合の異なる TOTP シークレット、既存セットに未使用コードが残っている場合の新しいバックアップコード、すでにこのユーザーまたは他のユーザーに登録されている WebAuthn クレデンシャルが該当します。既存のバックアップコードがすべて使用済みの場合、移行されたコードが使い果たされたセットを置き換えます。エラーにはクレデンシャル値は含まれません。
いずれかの要素が検証に失敗した場合、全体の結果が無効な認証情報として扱われ、何も書き込まれません。
移行された WebAuthn クレデンシャルはすぐに MFA で利用できますが、ユーザーが一度 MFA を完了するまではパスキーサインインには使えません。最初の MFA 検証でクレデンシャルのドメインが記録され、パスキーサインイン時にそれが必要となります。
要素は一度だけ書き込まれます。移行が成功した後は、以降のサインインでローカルパスワードが検証され、このアクションはそのユーザーに対して再度実行されません。
mfaVerifications には長期間有効な認証情報が含まれます。TOTP シークレット、バックアップコード、WebAuthn クレデンシャルデータをログに記録したり、エラーに含めたり、mfaVerifications 以外で返したりしないでください。
移行例
LEGACY_VERIFY_URL と LEGACY_API_TOKEN をアクションの環境変数として設定し、次のスクリプトをレガシー API に合わせて調整してください:
const runAction = async ({ event, environmentVariables = {} }) => {
const response = await fetch(environmentVariables.LEGACY_VERIFY_URL, {
method: 'POST',
headers: {
'content-type': 'application/json',
authorization: `Bearer ${environmentVariables.LEGACY_API_TOKEN}`,
},
body: JSON.stringify({
identifier: event.identifier,
password: event.password,
}),
});
// 認証 (Authentication) 拒否を通常の無効な認証情報として扱う
if (response.status === 401 || response.status === 404) {
return;
}
if (!response.ok) {
throw new Error(`レガシー認証 (Authentication) サービスが ${response.status} を返しました`);
}
const legacyUser = await response.json();
if (!legacyUser.passwordVerified) {
return;
}
return {
action: event.user ? 'updateUser' : 'createUser',
passwordVerified: true,
user: {
...(legacyUser.name && { name: legacyUser.name }),
customData: {
migratedFrom: 'legacy',
legacyUserId: legacyUser.id,
},
},
};
};
レガシーユーザーが MFA 要素を持っている場合は、同じ結果にマッピングしてください:
const toActionMfaVerifications = (legacyUser) => [
...(legacyUser.totpSecret
? [
{
type: 'Totp',
secret: legacyUser.totpSecret,
},
]
: []),
...(legacyUser.backupCodes?.length
? [
{
type: 'BackupCode',
codes: legacyUser.backupCodes,
},
]
: []),
...(legacyUser.passkeys ?? []).map((passkey) => ({
type: 'WebAuthn',
credentialId: passkey.credentialId,
publicKey: passkey.publicKey,
counter: passkey.counter,
})),
];
mfaVerifications: toActionMfaVerifications(legacyUser) を返却結果に追加してください。レガシーユーザーが MFA 要素を持っていない場合はこのフィールドを省略します。
最初に受け入れられたサインインの流れは次の通りです:
- ローカルパスワード認証 (Authentication) が失敗し、Logto がアクションを実行します。
- スクリプトが識別子とパスワードをレガシーシステムに送信します。
- レガシーシステムが認証情報を検証し、スクリプトが
createUserまたはupdateUserを返します。 - Logto がユーザーを作成または更新し、送信されたパスワードを新しいローカル Argon2i クレデンシャルとして保存し、移行された MFA 要素を書き込みます。
- 必要に応じてユーザーが MFA を完了し(移行要素を含む)、Logto がサインインを完了します。
- 以降のサインインでは、移行されたローカルパスワードが成功するため、このアクションはそのユーザーに対して呼び出されません。
セキュリティ境界
このアクションによるユーザー、パスワード、MFA の書き込みは、MFA 完了前に行われます。ユーザーが MFA を放棄または失敗した場合でも、これらの書き込みは残ります。
このアクションで作成されたユーザーは、登録専用ガード(メールブロックリスト、SSO 専用ドメインルール、サインアップ無効モード、登録必須プロフィールチェックなど)をバイパスします。センチネル保護と MFA は引き続き適用されます。
次のセーフガードを使用してください:
- レガシーシステムが送信されたパスワードを正確に検証した場合のみ
passwordVerified: trueを返す。 - レガシーエンドポイントは可能な限り非公開にし、サービス認証を要求し、HTTPS を使用し、レート制限を適用する。
- 返却するユーザーパッチは最小限にとどめる。未検証の識別子やプロフィールデータをコピーしない。
- TOTP シークレット、バックアップコード、WebAuthn クレデンシャルデータは認証情報として扱う。ログに記録したり、
customDataに格納したり、エラーに含めたりしない。 - 未知ユーザー作成、既存ユーザー更新、識別子衝突、停止ユーザー、MFA 移行と競合、上流障害、同時試行をテストする。
- 監査ログ で
Action.PostFirstFactorVerificationを監視する。 - 実用上可能な場合は、移行期間中のみアクションを有効にしておく。
事前にユーザーデータと互換性のあるパスワードハッシュをエクスポートできる場合は、一括ユーザー移行 の利用も検討してください。