See api-docs Menu

Logging a User In Via API

Use the OneLogin User API to log a user in, with or without MFA, in one of two ways:

  • By validating their password (also known as delegated authentication)

  • By creating a session token

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:

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 primarily 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.

As indicated in step 1, 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

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. On the other hand, receipt of a 401 Unauthorized status tells you that the user could not be authenticated.

To pick up at step 3 of the flow, have your app server receive the session_token returned by the Create Session Login API.

And 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 OneLogin URL: https://admin.{us_or_eu}.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://admin.{us_or_eu}.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://admin.{us_or_eu}.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://api.us.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"
        }
    ]
}

To pick up at step 3 of the flow, have your app server receive the session_token returned by the Verify Factor API.

And as described 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 this OneLogin URL: https://admin.{us_or_eu}.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.


Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

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

StackOverflow discussions about "[onelogin] user login api"

  • 2
    Votes
    1
    Answers

    Q: OneLogin session_via_api_token and Chrome

    Asked Nov 14 2016

    I am getting a session token via an ajax call. This in turn calls the API method https://api.us.onelogin.com/api/1/login/auth $.post("onelogin.ashx?action=sessiontoken", data, function (s … is now logged in. session_via_api_token returns response header "Location" with my original page URL. In Chrome the user is not logged in and the response header "Location" is https://app.onelogin.com/login I have a feeling it is a problem with cookies but can't figure out what. Any ideas? …

  • 1
    Votes
    1
    Answers

    Q: Implement custom connector to in-house applications

    Asked Dec 05 2016

    . But I was trying to figure out a way to just navigate the user to the OneLogin login portal and then redirect back to which ever in-house application the user is trying log into. If anyone has any suggestions or an idea on how to best implement this please let me know. … I am trying to figure out how custom connectors work or if it's the correct solution. Basically the company I work at wants to implement a "login using OneLogin" to our in-house applications and we …

  • 1
    Votes
    4
    Answers

    Q: OneLogin Create Session Login Token API returns status 400 with message: Bad Request

    Asked May 23 2016

    Request: //Get the session token for the specified user, using the token recieved from previous web request WebRequest request = WebRequest.Create("https://api.us.onelogin.com/api/1/login/auth … I am developing a C# application which needs to use the onelogin API to retrieve a session token. I am able to authenticate and and create a token with the following code: WebRequest Authrequest …

  • 1
    Votes
    3
    Answers

    Q: onelogin api with php curl 401 unauthorized

    Asked Jul 06 2016

    I have a simple curl request to the onelogin api written in PHP. The request works fine with my parameters from my terminal and I am able to login my user, however the php version I run on server … = "Authorization: bearer: ". $a_token; curl_setopt($ch, CURLOPT_URL, "https://api.us.onelogin.com/api/1/users"); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true …

  • 1
    Votes

    A: Accessing Third Party Apps After Creating A Session Via API Token

    Answered Mar 10 2017

    Two ways: If the app supports SP-initiated SAML, just navigate the user to the application and it'll do the whole SAML flow- App redirects to OneLogin - OL authenticates user (because you have … -for-a-user Take note that you're probably going to want to use the optional flag that makes sure to redirect to your login page, not OL's if you've built a login facade. …

Loading...