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 timeout after 10 seconds, causing to fail the hook.

Create Hook

Go to Dashboard > Hooks and click to + button from bottom right of the screen to create a hook. You will be redirected a page where you will enter the name, description, type of the hook and the content to execute. After you fill required fields you will see a save button appeared on the bottom right of the screen. Clicking that button will save your hook.

After saving the hook you can add any npm modules that supports Node.js v12. Also your content should be able to run on Node.js 12.

Your hook context must have a function named handle which receives two parameters. First parameter is a data parameter which contains hook context. See Hook Context for detailed information. The second parameter is a callback function which you should call with final hook context as second parameter when your job is done or with an error as first parameter you want to throw. Have a look at below for more concrete example:

function handle(data, callback){
  if(someCondition){
	  // hook executes successfully
	  callback(null, data)
  }else{
      // hook fails with an error
	  callback(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. You will see a table with sections of hook types. You can drag and drop the hooks in the same type change their order.

Adding Modules

After you create your hook, you can add modules for that hook by clicking Add npm package button from the left of the content editor. You will see a search bar on the screen where you can write down your npm package name that will be searched over npm registry. From the list you can click to the plus icon to add that module and you will see console output for that package installation. If the module already exists and its version is outdated you will see an update icon instead of plus icon to update the installed package.

Your modules must be compatible with NodeJS v14

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 whose structure will be the same as the real usage but it's content will be generated randomly.

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

Hook Context

key description
context.clientID Client Id that initiated the flow. Can be undefined in some hooks
context.clientName Client name that initated the flow. Can be undefined in some hooks
context.request.query Query parameters for initiated request
context.request.body Request body for initiated request
context.request.userAgent UserAgent for initiated request
context.request.ip IP of incoming request
context.accessToken Generated access token. Can be undefined in some hooks
context.idToken Generated id token. Can be undefined in some hooks
user PlusAuth user object. Can be undefined in some hooks

Hook Types

There are plenty of flows you can hook into. PRE hooks are running synchronously which will change the execution of the flow. However, POST hooks doesn't affect execution of the flow and even they fail the flow will continue successfully. This means, if you provide an error to the callback PRE hooks will fail that flow but POST hooks won't affect the flow execution.

PRE LOGIN

Hooks registered with this type will execute before users sign in process. This hook will be executed if the user exists even if password verification failed.

POST LOGIN

Hooks registered with this type will be executed when all the checks have passed for sign in process and user is successfully logged in to the system.

PRE REGISTER

Hooks registered with this type will be executed just before saving the user to the database or to the external connection. If you modify the user object in this hook, modified version will be saved into the database.

POST REGISTER

Hooks registered with this type will be executed when user is successfully stored into database or external connection.