Overview

Adding Mutli-Factor Authentication (MFA) to your application is a sure fire way to increase security and prevent unauthorized access to user accounts. OneLogin provides a series of API endpoints that let you manage MFA for your users. You can enroll multi-factor devices, trigger the sending of One-Time Password (OTP) codes via SMS or Push notification and, Verify codes to authenticate users. The most common workflow for MFA is add an additional layer of security at login time. However using these API’s you can add MFA code verification to any process that would benefit from additional security.

Endpoints

Get Available Factors Enroll a Factor Get Enrolled Factors Activate a Factor Verify a Factor

Postman Collection

Sample Workflows

Passwordless login using MFA This sample shows how you can delegate authentication to OneLogin without requiring the user to remember a password. Instead they will enter their username and a one-time code to verify their identity.
Using OneLogin Protect Push Notifications A variation to the Passwordless login that triggers push notifications to the OneLogin Protect app.
Sending codes via SMS Another variation to the Passwordless login that sends a one-time password to the user via SMS.
Standard login using MFA with OneLogin session creation Do a standard login using username & password with the requirement of MFA and also obtain a session token that can be used to access other OneLogin applications.

To provide OneLogin authentication with MFA in your app’s authentication flow, your app must do the following:

Get a bearer access token, using the Generate Tokens v2 API. The most restrictive API in this flow requires a scope of Manage Users or Manage All for the API credentials you use to generate the token.
Prompt the user for their username or email address.

Get the user ID, using the Get Users API. Pass the username or email address to the API to return the ID.

Sample request:

GET https://<subdomain>.onelogin.com/api/1/users?username=ashley.akua

Sample response:

{
   "status":{
      "error":false,
      "code":200,
      "type":"success",
      "message":"Success"
   },
   "data":[
      {
         "activated_at":"2009-05-05T00:00:00.000Z",
         "created_at":"2009-05-05T03:18:08.338Z",
         "email":"ashley.akua@onelogin.com",
         "username":"aakua",
         "firstname":"Ashley",
         "group_id":123456,
         "id":121212,
         ...
      }
   ]
}

Get the list of devices registered to the user in OneLogin, with their device IDs, using the Get Enrolled Authentication Factors API.

Sample request:

GET https://<subdomain>.onelogin.com/api/1/users/121212/otp_devices

Sample response:

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "Success",
        "error": false
    },
    "data": {
        "otp_devices": [
            {
                "active": true,
                "default": true,
                "auth_factor_name": "OneLogin SMS",
                "needs_trigger": true,
                "phone_number": "+1xxxxxxxxx",
                "type_display_name": "OneLogin SMS",
                "user_display_name": "Rich's Phone",
                "id": 525509
            },
            {
                "active": true,
                "default": false,
                "auth_factor_name": "OneLogin Protect",
                "needs_trigger": true,
                "type_display_name": "OneLogin Protect",
                "user_display_name": "OneLogin Protect",
                "id": 526532
            },
            {
                "active": true,
                "default": false,
                "auth_factor_name": "Google Authenticator",
                "needs_trigger": false,
                "type_display_name": "Google Authenticator",
                "user_display_name": "Google Authenticator",
                "id": 526551
            }
        ]
    }
}

Prompt the user to select their available device (if they have more than one registered device) and to enter their OTP code. If the selected device has needs_trigger: true then you MUST call the Activate a Factor API to trigger a SMS or Push notification and obtain a state_token. If the selected device has needs_trigger: false then you can accept a OTP code and immediately Verify it without supplying a state_token. Tip.* You don’t have to ask users with multiple registered devices to select their device if you write your app to loop through the devices and test the OTP code against each one.*
Verify the device ID and OTP code using the Verify a Factor API.
Grant access when verification returns success.

Using OneLogin Protect Push Notifications

If a user is using OTP Protect with “OTP push” (in which the authenticating client pushes an authentication request to the OneLogin Protect device, and the user simply accepts the request to complete authentication), then in steps 5 and 6 above, no otp_code is passed to the Verify a Factor API through the login prompt. Instead you will call Activate a Factor to trigger a Push notification to the OneLogin Protect app where the user will press Yes or No to accept the login. You will poll the Verify a Factor API until you either get a Success response or the state_token expires

Sending codes via SMS

If the OneLogin SMS factor has been selected in step 5 above, then you will make a call to Activate a Factor. This will send an OTP code to the user via SMS. You will then wait for the user to enter the otp_token and supply it along with the state_token to the Verify API to complete the authentication.

Note. This flow is described at length in Logging a User in Via API, “Flow with MFA.” To provide authentication and start a OneLogin session using a password and second authentication factor, your app must do the following:

Get a bearer access token, using the Generate Tokens v2 API.
Prompt the user for their username or email address and password.
Get a session token by posting the user’s credentials to the Create Session Login Token API.
If authentication requires a second authentication factor, the Create Session Login Token API returns a message that MFA is required and provides a list of MFA devices registered to the user.
Prompt the user to select their MFA device and enter their OTP code.
Verify the device ID and OTP code using the Verify Factor API. Note: This endpoint is different to the primary MFA Verify API as it also returns a session token.
If the Verify Factor API succeds in verifying the OTP code, it returns a session token to your app server.
After your app server receives the session token, it sends sends the token to the login page.
The login page posts the session token to the Create Session API via the browser. You can use either an HTML post or CORS request.
OneLogin starts a session for that user and sets session cookies in the user’s browser to log the user into your app. For a more detailed workflow description, including diagrams and code snippets, see Logging a User in Via API.