Hooks

There will be times you want to modify some flows or you want to apply some logic for some actions. PlusAuth provides hooks for you to be able to modify the flow and use your own logic.

Hooks are executed on a secure sandbox, and they will throw timeout error after 10 seconds, causing to fail the hook.

Create Hook

Go to Dashboard > Hooks. Here you will see a graph with flows located in top. After selecting your flow, click to Add Hook button from which step you would like to create the hook. You will be prompted with a dialog to enter your code and hook's name.

Your hooks characteristics are as following:

  • The code must be a valid JavaScript
  • The code must be in ESM format, meaning, you must use import, export etc.
  • The code must export a function named handle
  • handle function receives a data argument and a callback function as last argument, but it also can be an async function.
  • Hooks have 10 seconds lifetime. After 10 seconds the hook will throw a TimeoutError and will result of failing that hook.
  • You can use any npm package with the prefix of npm:. For example, npm:axios. Details at Modules Support
  • System level operations are not supported. For example, reading/writing files, executing system commands etc.

First argument the handle function receives contains hook context. See Hook Context for detailed information.

Have a look at below for more concrete example:

export function handle(data, callback) {
  if (someCondition) {
    // hook executes successfully
    callback(null, data)
  } else {
    // hook fails with an error
    callback(new Error('condition failed'))
  }
}

Alternatively, you can use promise-like interface like this:

export async function handle(data) {
  if (someCondition) {
    // hook executes successfully
    return data
  } else {
    // hook fails with an error
    throw new Error('condition failed')
  }
}

Change Order of Hooks

You can create hooks with the same type and their execution order could be somehow important for you. In those cases all you need to do is change the order for those hooks. Go to Dashboard > Hooks, drag and drop the hooks in the same container to change their order.

Modules Support

PlusAuth hooks supports usage of npm modules. You can use any npm modules from npm registry as long as it works on serverless environment.

A simple usage example:

import axios from 'npm:axios@^1'

export async function handle(data) {
  try {
    const response = await axios.get('https://httpbin.org/anything');
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
}
PlusAuth does not fix external modules versions. It is strongly advised to use fixed versions of packages. If you don't include the version, resolved package may change in future and that may or may not cause errors.

So instead of using npm:axios define its version as npm:[email protected]

Testing Hook

You can test your hook with the Run button located on the right sidebar of content editor. It will use a test context which contains will be in the same structure as the real usage, but it's content will be filled with dummy data.

After you click the Run button from the right side of the editor you will see console output and resulting context from the console window.

Hook Context

keydescription
clientClient object that initiated the flow.
userPlusAuth user object.
context.externalUserExternal user object retrieved from external connection such as LDAP
context.connectionCurrent connection name
context.request.queryQuery parameters for initiated request
context.request.bodyRequest body for initiated request
context.request.headersRequest headers for initiated request
context.request.userAgentUserAgent for initiated request
context.request.ipIP of incoming request
context.response.bodyResponse body object
context.response.headersHeaders which will be sent
context.authParamsAuthorization related params.
context.accessTokenGenerated access token.
context.idTokenGenerated id token.
context.mfaMFA related actions.
Some of the properties listed above could be undefined or null in some hook types or flows. Make sure to handle cases for them being undefined in your hook code.