1. Home >
2. API >
3. 2 >
4. Smart Hooks >
5. Overview

Overview

Smart Hooks offers a new way to extend OneLogin in ways never possible before. From creating conditional access login flows to augmenting user lifecycle events we can’t wait to see what you build.

We have several types of hooks planned primarily around authentication flows and user lifecyle events. The initial release of Hooks includes our first authentication level hook, called the Pre-authentication Hook.

Use this set of APIs to manage your Hooks. You will find endpoints to create, update, delete Smart Hooks as well as defining environment variables and accessing execution logs.

What is a Smart Hook?

A Smart Hook is an extension point in OneLogin that lets you define customized actions using Javascript code. You will use the Smart Hooks API to configure a javascript function that gets executed every time a specific hook fires.

Smart Hooks are serverless which means that OneLogin will host and execute the javascript functions for you. There is no need to catch and consume these hooks like you may have done in the past using our Event Webhooks.

Within a Hook you can import external helper modules, make requests to 3rd party or home grown APIs and in some cases return data that will alter a workflow in OneLogin.

For example, you may want to use a pre-authentication hook to dynamically change the Users Policy during a login flow.

Creating a Smart Hook

Smart Hooks are defined and created via the OneLogin API. Your javascript hook function is supplied as a base64 encoded string and submitted along with other configuration values. When a hook is created or updated the changes are reflected immediately and will be propgated to our supported operating regions within a few minutes.

Here is an example of the payload required to create a pre-authentication hook.

{
  "type": "pre-authentication",
  "function": "CmV4cG9ydHMuaGFuZGxlciA9IGFzeW5jIChjb250ZXh0KSA9PiB7CiAgICBjb25zb2xlLmxvZyhjb250ZXh0KQogICAgcmV0dXJuIHsKICAgICAgICB1c2VyOiBjb250ZXh0LnVzZXIKICAgIH0KfQo=",
  "disabled": false,
  "runtime": "nodejs18.x",
  "retries": 0,
  "timeout": 1,
  "options":{
    "risk_enabled": false,
    "location_enabled": false,
    "mfa_device_info_enabled": true
  },  
  "env_vars": [
  ],
  "packages": {
  }
}

Hook Types

There are several different types of Smart Hooks which allow for extending or customizing workflows within OneLogin. Each Smart Hook has its own request context and expected response behavior.

See the docs for each Smart Hook type for more detail on they work.

• Pre-Authentication Hook
• User-Migration Hook

Hook Context

A context object is passed into every hook function. The context varies based on the type of hook but can include information about the current user, their mfa devices, location, risk score etc.

Context is versioned which allows for new attributes to be added or removed as Smart Hooks matures. You can specify which version of context should be supplied to your hook using the context_version attribute.

{
  "context_version": "1.0.0",
  ...
}

For more detail on specific context attributes see the docs for the type of hook you are implementing.

Hook Response

The type of response required from your Smart Hook function varies based on the type of hook that is being implemented.

For example the pre-authentication hook expects a user policy ID to be returned so that it can alter the login flow. Where as the user-migration hook expects a hydrated user object so the user can be created in OneLogin during an authentication flow.

For more detail on specific hook responses see the docs for the type of hook you are implementing.

Environment Variables

In some cases you may want to make an external API request from a Hook and therefore need to include an API key in your hook function. Instead of hard coding secrets like API keys into your functions you should consider using an Environment Variable.

Environment Variables are not just useful for injecting secrets into your hooks. You can also use them inject common settings that may be useful across multiple different hooks.

It’s worth noting that if you update an environment variable, all of the hooks that have been linked to that variable will also be updated with the latest value.

How to use an environment variable in a hook

First create a environment variable using the API.

curl --location --request POST 'https://<subdomain>.onelogin.com/api/2/hooks/envs' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "SECRET_API_KEY",
    "value": "helloworld"
}'

Then create or update a hook including the new environment variable name.

{
  "type": "pre-authentication",
  "function": "",
  "disabled": false,
  "runtime": "nodejs18.x",
  "retries": 0,
  "timeout": 1,
  "options": {
    "risk_enabled": true,
    "location_enabled": false,
    "mfa_device_info_enabled": true    
  },
  "env_vars": [
    "SECRET_API_KEY"
  ],
  "packages": {
    "axios": "0.21.1"    
  },
  "conditions": [
    {
        "source": "roles",
        "operator": "~",
        "value": "123456"
    }
  ]  
}

Finally, access the variable by name from the standard Node.js environment object in your function code.

exports.handler = async (context) => {
  
  const apiKey = process.env.SECRET_API_KEY;

  // Do something with API key...

  return {
    user: context.user
  }
}

Runtime Environment

Smart Hooks must be written in Javascript and are executed using a stable version of Node.js.

Current Node version is nodejs18.x

You must set the runtime attribute of each hook to one of the supported versions.

NPM Modules

You can give your hooks super powers by pulling in useful packages from NPM. You will be responsible for managing package versions and upgrading when required.

When creating or updating a hook use the packages attribute to make them available in your hook function code. You can then use the require method to make use of the package.

Included packages require that an explicit semantic version is set.

For example, Create a hook with MySQL package to enable access to an external database.

{
    "type": "pre-authentication",
    "function": "CmV4cG9ydHMuaGFuZGxlciA9IGFzeW5jIChjb250Z....",
    "disabled": false,
    "retries": 0,
    "timeout": 1,
    "risk_enabled": false,
    "location_enabled": false,
  "mfa_device_info_enabled": false,
    "env_vars": [
    ],
    "packages": {
      "mysql": "2.18.1"
    }
}

Then require it in your function.

const mysql = require("mysql");

exports.handler = async (context) => {

  // Do something with mysql

  return {
    user: context.user
  }
}

Execution Timeouts

To ensure a good end user experience, Smart Hooks have execution timeouts in place.

The minimum timeout required for all hook types is 1 second.

The maximum timeout value varies for each type of hook.

Hook Type	Maximum Timeout
pre-authentication	1

Logs & Debugging

When you’re getting started and in the development or experimentation phase we recommend using a developer or sandbox account for testing your Hook functions.

We also provide a convenient logs endpoint for each hook which will provide the last 7 days of execution history. These logs are great for inspecting values in your hooks or catching and reporting errors.

Anything that is logged using console.log() or console.error() will be included in the logs.

For example, log the context object so you can inspect its values.

exports.handler = async (context) => {

  console.log("Context: ", context);

  return {
    user: context.user
  }
}

or catch and report errors

exports.handler = async (context) => {
  try {

    // Do something that causes an error... 

    return {
      user: context.user
    }
  }
  catch (error) {
    console.error("Error", error);
    return null;
  }
}

Postman Collection

We’ve created a library of sample Hook functions in the Postman collection. We will keep it updated with functions that solve common requested workflows.

To view & modify the function click on the Pre Request Script tab within Postman. Also note that this script will Base64 encode the function before it sends it to the Smart Hooks API.

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

Blog: Top 5 Reasons to Use a Pre-Authentication Smart Hook

---