Authing Docs

# Pipeline function development guide

Pipeline is a set of functions. The difference from ordinary hooks is that the function data in the entire pipeline can be transferred to each other to achieve the same effect as an industrial pipeline. This design pattern can make developers' custom functions more modular and easy to manage.

For security reasons, Authing will use your user pool ID (userPoolId) and user pool key (secret) to initialize authing-js-sdk in a special way. This process will not send your user pool key to the public network. You can use the global variable authing, **Do not initialize the SDK again! **

# Pipeline function type

Currently Authing supports three types of Pipeline functions:

Name Description
Pre-Register Pipeline Pre-Register Pipeline, which will be triggered every time the user officially enters the registration logic. Developers can use this to implement functions such as registering mailbox whitelist and registering IP whitelist.
Post-Register Pipeline After registration, the Pipeline will be triggered every time the user completes the registration logic (** it has been saved to the database at this time**). Developers can use this implementation to write custom metadata to the database and new user registration webhook Notification and other functions.
Post-Authentication Pipeline Post-Authentication Pipeline will be triggered every time the user completes the authentication. Developers can use this to implement functions such as adding custom fields to the token.
Pre-OIDCTokenIssued Pipeline Triggered before OIDC application code is changed to token, developers can use this to implement functions such as writing custom fields to idToken. For details of the code replacement token part of the OIDC authentication process, please see: Use OIDC Authorization.

Developers must choose a Pipeline type when creating a Pipeline function.

# Function definition

Pipeline function definition:

async function pipe(user, context, callback)

Pre-Register Pipeline Because it is impossible to confirm who this user is before registration, user is null.

The pipe function supports async / await syntax!

Do not rename the pipe function!

Parameter Description:

Parameters Type Description
user object The current requesting user. See user object for detailed fields.
context object Request authentication context. See context object for detailed fields.
callback function Callback function, see below for the usage document.

# callback function

definition:

function callback(error, user, context)

Description:

  1. The first parameter of the callback function represents the error that the developer wants to pass to the end user. If it is not null, the entire authentication process will be interrupted and the error will be returned directly to the front end.
  2. If the first parameter is null, be sure to pass the latest user and context to the callback function, otherwise the pipeline function will not work normally.

# Set up asynchronous execution

The pipeline function set to asynchronous execution (here at the asynchronous non-language level) will not block the execution of the registration, login, and OIDC processes. The parameters passed in the callback function have no effect on the subsequent processes and are suitable for asynchronous notifications. Scenarios, such as Feishu group notification, Dingding group notification, triggering external system statistics, etc.

As shown in the figure below, check this box to let the pipeline function execute asynchronously:

# Pipeline function example

Here we implement a Pre-Register Pipeline for the whitelist of registered mailbox suffixes.

async function pipe(context, callback) {
  const email = context.data.userInfo.email;
  // Non-mailbox registration method, skip this pipe function
  if (!email) {
    return callback(null, context);
  }

  // If the domain name mailbox is not example.com, an Access denied. error is returned to the terminal.
  if (!email.endsWith("@example.com")) {
    return callback(new Error("Access denied."));
  }
  return callback(null, context);
}

Briefly explain the code:

  • Lines 2-6 determine whether email is included in the request parameters, and if so, it means the email registration method. If not, skip this pipe function directly, and call callback with null and context parameters (Don't forget this parameter!). Of course, if you just want to register by email, this step is fine if there is no email to return an error~
  • Lines 8-10 determine whether the domain name of the mailbox is example.com. If the callback function is not called, the first parameter is new Error('Access Denied.').
  • On line 11, call return callback(null, context), then enter the next pipe function, if any.

← Usage →