See api-docs Menu


The user-migration hook runs synchronously as part of a UI based login flow and allows for the progressive migration of user records into OneLogin.

This hook is useful if you are migrating to OneLogin but don’t have the option to move users in bulk, which may be the case if you have a proprietary or unspported password hashing algorithm.

The user-migration hook is only triggered for emails/usernames that are not found in OneLogin. Assuming that your hook sucessfully validates the user credentials and retrieves user information, then the next time the user logs in they will be authenticated against the OneLogin user directory.

Pre-Authentication Smart Hook

Hook Context

A context object is passed into every hook function. The context contains the username and password that has been entered. It goes without saying that this is sensitive information and should not be logged.

To enable the continuous improvements and upgrades the context is also versioned. With each version of the context some attributes may be added or removed so you should always check to see that your Smart Hook still functions as expected if you change the context version.

When creating a new user-migration hook the latest version of the context will be used. You can use prior context versions by specifying the context_version attribute in your Smart Hook config.

Hook Config Options

There are currently no configuration options are specific to the User-Migration hook.

Version 1.0.0

  "user_identifier": "jim-hendrix",
  "password": "top-secret-password",
  "correlation_id": "13a97251-215d-4fa5-baaf-6fc15700a2db",
  "request_id": "7d436b7e-b4a3-4b48-83fd-f4a12c22bb62"

Context Attributes

user_identifier The username or email address entered by the user
password The password entered by the user
correlation_id A unique identifier that can be used to trace a transaction end to end. This is useful if you need help from OneLogin support in debugging any issues.
request_id A unique identifier that can be used to trace a single incoming request.

Hook Response

The user-migration hook gives you the opportunity to validate the user against an external database or user directory and then create the user in OneLogin.

When no user object is returned by the hook the login will be denied and the user will not be created in the OneLogin user directory.

exports.handler = async (context) => {

  // Check if the user exists against an external directory
  const externalApi = require("my-external-api-connector");
  let external_user = externalApi.validateUser(context.user_identifier, context.password);

  // If the users exists then build up a user object to return in the response
  if (external_user) {
    // Success - Create this user and proceed with the login
    return {
      success: true,
      user: {
        username: context.user_identifier,
        password: context.password,        
        firstname: external_user.first_name,
        lastname: external_user.last_name
  } else {
    // Fail - Dont create a user and deny access
    return {
      success: false,
      user: null

User Attributes


username or email is required

string A username for the user.

username or email is required

string A valid email for the user.


string The password to set for a user.
firstname string The users first name
lastname string The users last name
title string The users job title
department string The users department
company string The company the user belongs to
comment string Free text related to the user
group_id integer The ID of the Group in OneLogin that the user will be assigned to
role_ids array A list of OneLogin Role IDs the user will be assigned to.
phone string The E.164 format phone number for a user.
directory_id integer The ID of the OneLogin Directory the user will be assigned to
trusted_idp_id integer The ID of the OneLogin Trusted IDP the user will be assigned to
manager_ad_id integer The ID of the users manager in Active Directory
manager_user_id integer The OneLogin User ID of the users manager
samaccountname string The users Active Directory username
member_of string The users directory membership
userprincipalname string The principle name of the user
distinguished_name string The distinguished name of the user
external_id string The ID of the user in an external directory

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.

Postman Pre Request Script

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.

Run in Postman

    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.

Have a Question?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

Have a product idea or request? Share it with us in our Ideas Portal.