跳到主要内容

Actions

Logto Actions 允许你在认证 (Authentication) 流程的特定节点运行受信任的 JavaScript。Action 是同步执行的：认证 (Authentication) 请求会等待脚本执行，脚本结果可以更新用户或决定流程是否继续。

当决策必须在认证 (Authentication) 流程内部发生时，Actions 非常有用。常见用例包括：

  • 用户首次登录时，从旧有身份系统迁移用户和密码。
  • 在 Logto 完成登录前，刷新用户资料或应用特定数据。
  • 调用外部服务并将其结果应用到 Logto 用户。
备注:

Actions 仅在 Logto Cloud 企业版计划中可用。

注意:

Action 脚本可以影响认证 (Authentication) 并修改用户数据。只有受信任的管理员才应被允许查看、创建、编辑、测试、启用或删除它们。

在自托管部署中，Action 脚本在 Logto 服务器进程内以其权限运行。授予脚本编辑或测试权限等同于授予 Logto 主机上的代码执行权限，因此不应将管理控制台与不受信任的用户共享。将脚本视为受信任的服务端代码；运行时会限制脚本的时间和内存，但这不是针对不受信任代码的安全边界。

Actions 在登录流程中的作用​

Logto 目前提供两种 Action 类型：

Action 类型运行时机可执行操作
首次因子验证后在密码登录过程中，仅当 Logto 的本地密码验证失败时运行。本地密码有效时不会运行。针对旧有系统验证提交的凭据，然后创建新的 Logto 用户或更新现有用户，并迁移提交的密码。
登录后用户完成所有认证 (Authentication) 因子（包括需要时的 MFA）后，Logto 完成登录并签发令牌之前。使用最终登录上下文更新和丰富现有 Logto 用户。

两种 Action 类型仅在 Experience API 的 SignIn 交互中运行。首次因子验证后仅适用于密码登录；登录后 Action 与认证 (Authentication) 方法无关。

脚本模型​

每种 Action 类型都有一个配置和一个名为 runAction 的 JavaScript 入口函数：

const runAction = async ({ event, environmentVariables = {} }) => {
  // 检查 event，可选地获取外部数据，并返回该 Action 类型支持的结果。
};

参数包含：

  • event：生产环境下的认证 (Authentication) 事件。其结构取决于 Action 类型。
  • environmentVariables：为该 Action 配置的字符串值。这些值通过函数参数传递；无法通过 process.env 获取。

编辑器提供类型信息，但保存的脚本会作为 JavaScript 执行。脚本可以是异步的，并且在 Logto Cloud 和自托管 Logto 中都可以使用以下标准 Web API：

  • fetch、Request、Response 和 Headers
  • 通过 crypto 和 crypto.subtle 使用 Web Crypto
  • TextEncoder 和 TextDecoder
  • URL 和 URLSearchParams

脚本不能导入包。请避免使用 Node.js 特有的全局变量和模块，因为它们在自托管 Logto 与 Logto Cloud 之间不可移植，也不属于支持的脚本约定。

每种 Action 类型支持的返回结果不同；在启用 Action 前请参阅对应的参考页面。

Actions 与 Webhook 的区别​

Actions 和 Webhook 用途不同：

ActionsWebhook
执行方式同步，嵌入认证 (Authentication) 流程异步，认证 (Authentication) 请求之外
能否影响当前认证 (Authentication) 流程可以不可以
能否通过结果修改用户可以，使用支持的用户补丁不能直接修改；接收方可单独调用 Management API
事件覆盖范围选定的认证 (Authentication) 节点广泛的交互和数据变更事件
典型用途凭据迁移、令牌前用户资料丰富通知、下游同步、分析

异步操作请放在 Webhook 中。只有当 Logto 需要在认证 (Authentication) 继续前获得结果时，才使用 Action。

下一步​