Authing 文档文档
快速开始
概念
使用指南
开发集成 arrow
  • V2 文档
  • V3 文档
元数据
应用集成
身份自动化
加入 APN
开发集成
多租户(内测版)
控制台文档
多租户控制台
租户控制台
Saas 应用 Demo
快速开始
概念
使用指南
开发集成 arrow
  • V2 文档
  • V3 文档
元数据
应用集成
身份自动化
加入 APN
开发集成
多租户(内测版)
控制台文档
多租户控制台
租户控制台
Saas 应用 Demo
旧版
使用指南
  • 快速开始

  • 对用户进行认证

  • 对用户进行权限管理

  • 用户自助服务

  • 授权

  • 自适应 MFA

  • 管理用户账号

  • 管理用户目录

  • 同步中心

  • 应用

  • 成为联邦认证身份源

  • 连接外部身份源(IdP)

  • 微信生态全场景能力

  • 迁移用户到 Authing

  • 管理组织机构

  • 安全设置

  • 品牌化

  • 自动化

    • 流水线 Pipeline

      • 创建你的第一个 Pipeline 函数
      • Pipeline API Reference
      • Pipeline 的应用场景
      • Pipeline User 对象
      • Pipeline Context 对象
      • 在 Pipeline 中使用环境变量
      • 可用的 Node Modules
      • 如何调试
      • 私有化部署
    • Webhooks
    • 身份自动化
  • 审计日志

  • 设置

  • Authing 令牌
  • 私有化部署方案

  • 常见问题 FAQ

  1. 使用指南
  2. /
  3. 自动化
  4. /
  5. 流水线 Pipeline
  6. /
  7. Pipeline API Reference

¶ Pipeline 函数开发指南

更新时间: 2025-02-18 09:00:47
编辑

Pipeline 为一组函数,和普通 Hooks 的区别在于,Pipeline 整个流程中的函数数据可以相互传递,实现工业流水线一样的效果。这种设计模式,可以使得开发者的自定义函数更加模块化,便于管理。

出于安全考虑, Authing 会通过特殊方式,使用你的用户池 ID(userPoolId) 和用户池密钥(secret) 初始化 authing-js-sdk,此过程不会将你的用户池密钥发送到公网。你可以使用使用全局变量 authing,请勿再次初始化 SDK!

¶ Pipeline 函数类型

目前 Authing 支持六种类型的 Pipeline 函数:

触发场景说明
注册前在每次用户正式进入注册逻辑前触发,此时用户信息还没有保存至数据库。开发者可在此自定义控制用户的注册流程,实现注册邮箱白名单、注册 IP 白名单等功能。
注册后在每次用户完成注册逻辑之后触发,此时用户信息已经保存至数据库。开发者可在此获取并自定义扩展用户的注册信息,实现往数据库写入自定义 Metadata 、新用户注册 webhook 通知等功能。
认证前在每次用户完成认证之前触发,此时还没有在数据库内写入登录信息。开发者可在此自定义控制用户的登录流程,实现在特定时间段禁止用户登录,阻止可疑 IP 登录等功能。
认证后在每次用户完成认证之后触发,此时已经在数据库内写入登录信息。开发者可在此获取并自定义扩展用户的登录信息,实现将用户位置信息写入 Metadata,使用 ui-avatars 生成用户头像等功能。
OIDC ID Token 签发前OIDC 应用签发 ID Token 之前触发(只在授权码模式、隐式模式、密码模式下触发)。开发者可在此向 ID Token 中写入自定义字段。
OIDC Access Token 签发前OIDC 应用签发 Access Token 之前触发。开发者可在此向 Access Token 中写入自定义字段。

请勿在「注册后」和「认证后」两个场景中断正常认证流程,否则会导致数据库数据和返回结果不一致,从而出现不可预料的错误!

在 OIDC 认证流程中,授权码模式、隐式模式、密码模式和编程访问账号模式都会签发 Access Token,并触发对应的 Pipeline 函数。

当使用编程访问账号进行认证时,不会签发 OIDC ID Token,对应的 Pipeline 函数也不会触发。

OIDC 应用使用授权码换取 ID Token 和 Access Token 的详细过程请参见:使用 OIDC 授权。

OIDC 编程访问账号使用 Client ID 和 Client Secret 换取 Access Token 的详细过程请参见:M2M 授权

¶ 函数定义

Pipeline 函数定义:

async function pipe(user, context, callback)

参数说明:

参数类型说明
userobject当前请求用户。详细说明请见 user 对象。
contextobject请求认证上下文。详细说明请见 context 对象。
callbackfunction回调函数,使用文档见下文。

请勿重命名 pipe 函数!

注册前触发的 Pipeline 函数的 user 参数为空,因为此时用户对象还没有生成。

当使用编程访问账号进行认证时,OIDC Access Token 签发前触发的 Pipeline 函数的 user 参数为空,因为编程访问账号不存在用户的概念。

pipe 函数支持 async / await 语法!

¶ callback 函数

定义:

function callback(error, user, context)

当你的 Pipeline 函数完成了所需处理,需要向 Authing 的后端返回数据,或是需要中断认证流程时,都需要在代码返回前调用 callback 函数。

参数说明:

参数类型说明
errorobject错误对象。如果不为 null,整个认证流程将会中断,直接返回错误给前端。
userobject作为返回值的用户对象,其值将会被后端利用,同时用作下一个 Pipeline 函数的参数。
contextobject作为返回值的上下文对象,其值将会被后端利用,同时用作下一个 Pipeline 函数的参数。

如果 error 参数不为 null ,请务必将最新的 user 和 context 传给 callback 函数,否则之后的 Pipeline 函数将无法正常工作。

¶ 设置异步执行

设置为异步执行( 这里的异步非语言层面上 )的 pipeline 函数不会阻塞注册、登录、OIDC 流程的执行,callback 函数传入的参数对后续流程无影响,适用于进行异步通知的场景,比如飞书群通知、钉钉群通知、触发外部系统统计等。

如下图所示,勾选上此框表示让该 pipeline 函数异步执行:

¶ Pipeline 函数示例

这里我们实现一个注册邮箱后缀白名单的 Pre-Register Pipeline。

async function pipe(context, callback) {
  const email = context.data.userInfo.email;
  // 非邮箱注册方式, 跳过此 pipe 函数
  if (!email) {
    // 注意参数
    return callback(null, context);
  }

  // 如果域名邮箱不是 example.com, 返回 Access denied. 错误给终端。
  if (!email.endsWith("@example.com")) {
    return callback(new Error("Access denied."));
  }
  // 进入下一个 pipe 函数(如果有)
  return callback(null, context);
}
上一篇: 创建你的第一个 Pipeline 函数 下一篇: Pipeline 的应用场景
  • Pipeline 函数类型
  • 函数定义
  • Pipeline 函数示例

用户身份管理

集成第三方登录
手机号闪验 (opens new window)
通用登录表单组件
自定义认证流程

企业内部管理

单点登录
多因素认证
权限管理

开发者

开发文档
框架集成
博客 (opens new window)
GitHub (opens new window)
社区用户中心 (opens new window)

公司

400 888 2106
sales@authing.cn
北京市朝阳区北辰世纪中心 B 座 16 层(总)
成都市高新区天府五街 200 号 1 号楼 B 区 4 楼 406 室(分)

京ICP备19051205号

beian京公网安备 11010802035968号

© 北京蒸汽记忆科技有限公司