アクション (Actions)
Logto アクション (Actions) を使うと、認証 (Authentication) フローの特定のタイミングで信頼された JavaScript を実行できます。アクションは同期的に実行されます：認証リクエストはスクリプトの完了を待ち、スクリプトの結果によってユーザーの更新やフローの継続可否が決まります。
アクション (Actions) は、認証 (Authentication) フロー内で判断を下す必要がある場合に便利です。主なユースケースは次の通りです：
- 初回サインイン時にレガシーアイデンティティシステムからユーザーやパスワードを移行する。
- Logto がサインインを完了する前に、ユーザープロファイルやアプリケーション固有のデータを更新する。
- 外部サービスを呼び出し、その結果を Logto ユーザーに適用する。
アクション (Actions) は Logto OSS および Logto Cloud Enterprise プランで利用できます。
アクションスクリプトは認証 (Authentication) に影響を与え、ユーザーデータを変更できます。信頼できる管理者のみが閲覧、作成、編集、テスト、有効化、削除できるようにしてください。
セルフホスト環境では、アクションスクリプトは Logto プロセス内の仮想マシンで実行されます。信頼されたサーバーサイドコードとして扱い、信頼できないコードのセキュリティ境界とは見なさないでください。
アクション (Actions) がサインインに組み込まれる流れ
Logto では現在、2 種類のアクションタイプを提供しています：
| アクションタイプ | 実行タイミング | できること |
|---|---|---|
| 第一要素認証後アクション | パスワードサインイン時、Logto のローカルパスワード認証 (Authentication) が失敗した場合のみ実行。ローカルパスワードが有効な場合は実行されません。 | 提出された認証情報をレガシーシステムで検証し、新しい Logto ユーザーの作成や既存ユーザーの更新、パスワードの移行を行うことができます。 |
| サインイン後アクション | ユーザーがすべての認証 (Authentication) 要素（MFA を含む）を完了した後、Logto がサインインを完了しトークンを発行する前に実行。 | 最終的なサインインコンテキストを使って既存の Logto ユーザーを更新・拡張できます。 |
どちらのアクションタイプも Experience API の SignIn インタラクションでのみ実行されます。第一要素認証後アクションはパスワードサインイン時のみ適用され、サインイン後アクションは認証 (Authentication) 方法に依存しません。
スクリプトモデル
各アクションタイプには 1 つの設定と、runAction という名前の JavaScript エントリ関数があります：
const runAction = async ({ event, environmentVariables = {} }) => {
// event を確認し、必要に応じて外部データを取得し、
// このアクションタイプでサポートされる結果を返します。
};
ペイロードには次のものが含まれます：
event: 本番環境の認証 (Authentication) イベント。内容はアクションタイプによって異なります。environmentVariables: このアクション用に設定された文字列値。これらの値は関数ペイロード経由で渡され、process.envからは利用できません。
エディタは型情報を提供しますが、保存されたスクリプトは JavaScript として実行されます。スクリプトは非同期であり、注入された fetch 関数を使って外部 HTTPS API を呼び出すことができます。パッケージのインポートや require、process などの Node.js グローバルにはアクセスできません。
サポートされる結果はアクションタイプごとに異なります。アクションを有効化する前に、該当するリファレンスページを参照してください。
アクション (Actions) と Webhook の違い
アクション (Actions) と Webhook は異なる目的で使われます：
| アクション (Actions) | Webhook | |
|---|---|---|
| 実行タイミング | 認証 (Authentication) と同期的かつインラインで実行 | 認証 (Authentication) リクエストの外で非同期的に実行 |
| 現在の認証 (Authentication) フローに影響可能か | 可能 | 不可 |
| 結果からユーザーを変更できるか | サポートされるユーザーパッチで可能 | 直接は不可。受信側が Management API を別途呼び出し可能 |
| イベントカバレッジ | 選択された認証 (Authentication) ポイント | 幅広いインタラクションやデータ変更イベント |
| 主な用途 | 認証情報移行、トークン発行前のプロファイル拡張 | 通知、下流同期、分析 |
非同期処理は Webhook で行ってください。認証 (Authentication) 続行前に Logto が結果を必要とする場合のみアクション (Actions) を使用してください。