1. Home >
2. API >
3. 2 >
4. Smart Hooks >
5. Smart Hook Types >
6. User-Migration

User-Migration

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.

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 username or email is required	string	A username for the user.
email username or email is required	string	A valid email for the user.
password required	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.

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.

---