Actions
Logto Actions 讓你能在驗證 (Authentication) 流程的特定階段執行受信任的 JavaScript。Action 以同步方式執行：驗證請求 (Authentication request) 會等待腳本完成，腳本結果可以更新使用者或決定流程是否繼續。
當決策必須發生在驗證流程內時，Actions 特別有用。常見應用場景包括：
- 使用者首次登入時，從舊有身分系統遷移使用者與密碼。
- 在 Logto 完成登入前，刷新使用者個人資料或應用程式專屬資料。
- 呼叫外部服務並將其結果應用於 Logto 使用者。
Actions 可用於 Logto OSS 與 Logto Cloud Enterprise 方案。
Action 腳本會影響驗證 (Authentication) 並可修改使用者資料。僅應允許受信任的管理員檢視、建立、編輯、測試、啟用或刪除這些腳本。
在自架部署中，Action 腳本會在 Logto 程序內的虛擬機器中執行。請將其視為受信任的伺服器端程式碼，而非不受信任程式碼的安全邊界。
Actions 在登入流程中的角色
Logto 目前提供兩種 Action 類型：
| Action type | When it runs | What it can do |
|---|---|---|
| 第一驗證因子後 (Post first-factor verification) | 密碼登入期間，僅在 Logto 的本地密碼驗證失敗時執行。本地密碼有效時不會執行。 | 針對舊有系統驗證提交的認證資訊，然後建立新的 Logto 使用者或更新現有使用者並遷移提交的密碼。 |
| 登入後 (Post sign-in) | 使用者完成所有驗證因子（包含需要時的 MFA）後、Logto 完成登入並發放權杖前執行。 | 使用最終登入情境更新並豐富現有 Logto 使用者。 |
這兩種 Action 僅在 Experience API 的 SignIn 互動中執行。第一驗證因子後僅適用於密碼登入；登入後則與驗證方式無關。
腳本模型
每種 Action 類型都有一組設定與一個名為 runAction 的 JavaScript 入口函式：
const runAction = async ({ event, environmentVariables = {} }) => {
// 檢查 event，可選擇性抓取外部資料，並回傳此 Action 類型支援的結果。
};
傳入內容包含：
event：實際驗證事件，其結構依 Action 類型而異。environmentVariables：為此 Action 設定的字串值。這些值會透過函式參數傳遞；不會透過process.env取得。
編輯器會提供型別資訊，但儲存後的腳本會以 JavaScript 執行。腳本可為非同步，並可使用注入的 fetch 函式呼叫外部 HTTPS API。無法匯入套件或存取 Node.js 全域變數（如 require 或 process）。
每種 Action 類型支援的回傳結果不同；啟用 Action 前請參閱對應參考頁面。
Actions 與 Webhook
Actions 與 Webhook 用途不同：
| Actions | Webhook | |
|---|---|---|
| 執行方式 | 與驗證同步、內嵌於流程 | 非同步，於驗證請求之外執行 |
| 可否影響當前驗證流程 | 可以 | 不行 |
| 可否直接修改使用者 | 可以，透過支援的使用者 patch | 不行；但接收端可另行呼叫 Management API |
| 事件涵蓋範圍 | 精選驗證節點 | 廣泛的互動與資料變更事件 |
| 典型用途 | 認證遷移、發權杖前個人資料豐富化 | 通知、下游同步、分析 |
需進行非同步工作的情境請用 Webhook。僅當 Logto 必須在驗證繼續前取得結果時才使用 Action。