1. Home >
2. API >
3. 1 >
4. Login Pages >
5. Logging a User In Via API

Logging a User In Via API

You can use the OneLogin API to log a user in from a custom login page, with or without MFA.

If you want to use a session cookie to keep a OneLogin session open for your user (which has the added benefit of giving your user access to their other OneLogin-enabled apps during that session), you can use the Create Session Login Token API to generate a session token and the Create Session endpoint to start the session. If MFA is required, you must also call the Verify Factor API. This topic describes the workflow required to get a session token and create a session, with and without MFA.

If you simply want to authenticate a user in OneLogin (also known as delegated authentication), you can treat the token returned in the 200 OK - Success message as a confirmation that the user has been authenticated. You will not use the session token itself. While this topic is focused on the session token flow, it also calls out the API responses required to use the simpler delegated authentication approach.

Note: You can also log in a user via SAML assertion. For information about the SAML Assertion API,  see Generate SAML Assertion API.

Overview

Here is a high-level diagram of the login flow when using the Create Session Login Token API to log a user in to your app without MFA. A detailed description of this flow is provided in Flows without MFA, below.

Here is a high-level diagram of the login flow when using the Create Session Login Token API to log a user in to your app with MFA. Note that the flow is largely the same as the flow when MFA is not required, with the exception of an expansion of step 2 to include calls to the Verify Factor API. A detailed description of this flow is provided in Flows with MFA, below.

Shared flow

As indicated in step 1 of the diagrams above, both scenarios start with a user submitting OneLogin credentials through a login page in your app:

From this login page, as indicated in step 2, have your app server call the Create Session Login Token API and pass it the username_or_email and password, along with the user’s OneLogin subdomain value:

{
   "username_or_email":"ashley.akua",
   "password":"P@33w0rd!",
   "subdomain":"jhainc"
}

From here, the API flow can go in one of two directions:

• Flows without MFA

• Flows with MFA

Flows without MFA

If the call to the Create Session Login Token API in step 2 is a success and MFA is not required for the user, the response will include the following values:

{
    "status": {
        "type": "success",
        "message": "Success",
        "code": 200,
        "error": false
    },
    "data": [
        {
            "status": "Authenticated",
            "user": {
                "username": "ashley.akua",
                "email": "ashley.akua@onelogin.com",
                "firstname": "Ashley",
                "id": 88888888,
                "lastname": "Akua"
            },
            "return_to_url": null,
            "expires_at": "2016/01/07 05:56:21 +0000",
            "session_token": "9x8869x31134x7906x6x54474x21x18xxx90857x"
        }
    ]
}

Note: If you are using the Create Session Login Token API to do simple delegated authentication to validate a user’s password without MFA, receipt of the session_token value is all you need from the flow to tell you that the user has been authenticated. Likewise, receipt of a 401 Unauthorized status tells you that the user could not be authenticated.

At step 3 of the flow, have your app server receive the session_token returned by the Create Session Login API.

Next, as indicated in step 4, send it back to your app’s login page in the user’s browser.

Then, as indicated in step 5, have the login page use a form or a CORS request to post the session_token via the browser to the Create Session endpoint: https://{your_subdomain}.onelogin.com/session_via_api_token.

Example HTML Form Page

For example, here is a simple HTML page with a form submission. Replace the variables in curly brackets { }, open the page in your browser, and click the Submit button to see the login flow in action.

<!doctype html>
<html>
    <head>
        <meta charset="utf-8">
    </head>
    <body>
        <p>Auth API Test</p>
        <form action=
         "https://{your_subdomain}.onelogin.com/session_via_api_token" method="POST">
            <input type="hidden" name="session_token" value="{your session token value}">
            <input type="submit" placeholder="GO">
            <input id="auth_token" type="hidden">
        </form>
    </body>
</html>

As described in step 6, OneLogin will respond to the form post by starting a session for that user and setting the appropriate session cookies in the user’s browser to log the user in to your app. In the case of the example HTML form page, it will log the user in to the OneLogin app.

In your actual app, you’ll need to include logic to look at the redirect and behave appropriately. Your app starts by requesting the POST, but upon receiving a successful response, it must be able to recognize that the user is now logged in and respond appropriately by displaying a logged in state to the user, for example.

Example CORS Post

For example, here is a simple CORS post.

It must be posted from the URL that was specified using the Custom-Allowed-Origin-Header-1 header in the request to the Create Session Login Token API.

function makeCors(session_token) {
   var xhr = new XMLHttpRequest();
   xhr.withCredentials = true;
   method = "POST";
   var url = "https://{your_subdomain}.onelogin.com/session_via_api_token";
   xhr.open(method, url, true);
   xhr.setRequestHeader("Content-Type", "application/json");
   body = {"session_token": session_token};
   xhr.send(JSON.stringify(body));
 };   

As described in step 6, OneLogin will respond to the CORS post by starting a session for that user and setting the appropriate session cookies in the user’s browser to log the user in to your app. With CORS requests, there is no response to parse; the API simply sends a cookie to set the session on the browser.

Flows with MFA

If you are using the Create Session Login Token API to log a user in or to verify a user’s credentials (delegated authentication) with MFA, the Create Session Login Token API responds differently than when MFA is not required.

In response to submission of the username_email, password, and subdomain values via the login page in step 2, the Create Session Login Token API returns these values when MFA is required:

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "MFA is required for this user",
        "error": false
    },
    "data": [
        {
            "callback_url": "https://subdomain.onelogin.com/api/1/verify_factor",
            "user": {
                "email": "ashley@onelogin.com",
                "username": "ashley.akua",
                "lastname": "Akua",
                "firstname": "Ashley",
                "id": 88888888
            },
            "devices": [
                {
                    "device_type": "Google Authenticator",
                    "device_id": 222222
                },
                {
                    "device_type": "OneLogin OTP SMS",
                    "device_id": 999999
                }
            ],
            "state_token": "xx5x2x91331x3x3x341xx51176x7xxx182x65xxx"
        }
    ]
}

With a successful response from the Create Session Login Token API, you can display a prompt for the user to enter an MFA factor. For example, here are prompts for the OneLogin OTP SMS and Google Authenticator factors:

 

MFA - Authentication Pending

When the user clicks an option like OneLogin OTP SMS’s Send Security Code to mobile option in your own app UI, your UI should call the Verify Factor API as in step 2a and supply the device_id and state_token to start the MFA factor verification flow:

{
    "device_id": "999999",
    "state_token": "xx5x2x91331x3x3x341xx51176x7xxx182x65xxx"
}

For MFA factors that require the user to manually request an OTP, such as OneLogin OTP SMS, the otp_token value is not required in the initial call, and if not included, returns a 200 OK - Pending result, as in step 2b.

For example, this is the 200 OK - Pending response from the OneLogin OTP SMS MFA factor:

{
    "status": {
        "type": "pending",
        "code": 200,
        "message": "SMS token sent to your mobile device. Authentication pending.",
        "error": false
    }
}

You’ll make a subsequent Verify Factor API call, as in step 2c to provide the otp_token value once it has been provided to the user and the user submits it.

MFA - Authentication Immediate

For MFA factors that immediately provide an OTP value to the user, such as Google Authenticator, the otp_token value is required in the initial call to the Verify Factor API, as in step 2a, because it is immediately available to the user.

When the user clicks Log In, your app UI should call the Verify Factor API and supply the device_id, state_token, and otp_token values:

{
    "device_id": "222222",
    "state_token": "xx5x2x91331x3x3x341xx51176x7xxx182x65xxx",
    "otp_token": "123456"
}

session_token Response

In response to a valid MFA factor, the Verify Factor API will return the session_token value needed to start a session and log the user in. The Verify Factor API supplies this response to your app server, as in step 2c.

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "Success",
        "error": false
    },
    "data": [
        {
            "return_to_url": null,
            "user": {
                "username": "ashley.akua",
                "email": "ashley.akua@onelogin.com",
                "firstname": "Ashley",
                "lastname": "Akua",
                "id": 88888888
            },
            "status": "Authenticated",
            "session_token": "xxxxxxxxx8a4c07773a5454f946",
            "expires_at": "2016/01/26 02:21:47 +0000"
        }
    ]
}

At step 3 of the flow, have your app server receive the session_token returned by the Verify Factor API.

Next, as indicated in step 4, send it back to your app’s login page in the user’s browser.

Then, as indicated in step 5, have the login page use a form or CORS request to post the session_token via the browser to the Create Session endpoint: https://{your_subdomain}.onelogin.com/session_via_api_token.

As indicated in step 6, OneLogin will respond by starting a session for that user and setting the appropriate session cookies in the user’s browser to log the user in to your app.

Note that if you use an HTML POST (as opposed to a CORS request), you’ll need to include logic to look at the redirect and to behave appropriately. Your app starts by requesting the POST, but upon receiving a successful response, it must be able to recognize that the user is now logged in and respond appropriately by displaying a logged in state to the user, for example. For a CORS request, there is no response to parse; the API simply sends a cookie to set the session on the browser.

---