Pipeline 函数开发指南

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

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

Pipeline 函数类型

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

名称

说明

Pre-Register Pipeline

注册前 Pipeline,会在每次用户正式进入注册逻辑前触发,开发者可用此实现注册邮箱白名单、注册 IP 白名单等功能。

Post-Register Pipeline

注册后Pipeline, 会在每次用户完成注册逻辑之后触发(此时已经保存至数据库),开发者可用此实现往数据库写入自定义 metadata 、新用户注册 webhook 通知等功能。

Post-Authentication Pipeline

认证后 Pipeline 会在每次用户完成认证之后触发,开发者可用此实现往 token 加入自定义字段等功能。

Pre-OIDCTokenIssued Pipeline

OIDC 应用 code 换 token 之前触发,开发者可用此实现往 idToken 中写入自定义字段等功能。OIDC 认证流程的 code 换 token 部分详情请见:使用 OIDC 授权

开发者创建 Pipeline 函数时必须选择一种 Pipeline 类型。

函数定义

Pre-Register Pipeline 函数定义:

async function pipe(context, callback)

Post-Register Pipeline 和 Post-Authentication Pipeline 函数定义:

async function pipe(user, context, callback)

Pre-Register Pipeline 少了一个 user 参数,因为注册前无法确认此用户是谁。

pipe 函数支持 async / await 语法!

请勿重命名 pipe 函数!

参数说明:

参数

类型

说明

user

object

当前请求用户。详细字段请见 user 对象

context

object

请求认证上下文。详细字段请见 context 对象

callback

function

回调函数,使用文档见下文。

callback 函数

定义:

function callback(error, user, context)

或:

function callback(error, context)

说明:

  1. callback 函数的第一个参数表示是开发者希望传给终端用户的 error,如果不为 null,整个认证流程将会中断,直接返回错误给前端

  2. 如果第一个参数为 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.'));
}
return callback(null, context);
}

简要解释一下代码:

  • 2-6 行判断请求参数中是否包含 email, 如果有的话说明是邮箱注册方式。如果没有,直接跳过此 pipe 函数,调用 callback 的参数分别为 null 和 context(请勿忘记此参数!)。当然,如果你只是希望邮箱方式注册,这一步如果没有邮箱返回错误也是可以的 ~

  • 8-10 行判断邮箱域名是否为example.com,如果不是调用 callback 函数,第一个参数为 new Error('Access Denied.')

  • 11 行,调用 return callback(null, context),接着进入下一个 pipe 函数,如果有的话。