Authenticate User Process

Content

• Overview
• reCAPTCHA
• Process Flow
• App Settings
• User Journey Flow Diagram
• API Walkthroughs
• Error Codes
• Revision History

Overview

This Process defines how a user signs into ULM Cloud. This is a straightforward operation with additional options for additional user verification (e.g., two-factor authentication, reCAPTCHA).

Note: This Process operates differently from most other Processes, in that it is not started by the usual Start Process API (but from its own dedicated endpoint), and requires a mandatory payload in the request body.

reCAPTCHA

ULM Processes that involve authentication include support for reCAPTCHA, which is one of many different types of CAPTCHA. CAPTCHA is an automated, dynamically-generated challenge that the user must pass in order to proceed with authentication. These challenges are simple and easy for humans to pass, but difficult for malicious automated "bots" to bypass.

There are multiple types and versions of CAPTCHA, the criteria for when and how to challenge a user is dependent on the CAPTCHA type. For example, some versions prompt the user to click a checkbox, and prove they aren't a malicious bot, after a failed number of login-requests.

In other cases, the system instead requires the user to match images to further validate their identity.

By default, ULM Cloud supports Invisible reCAPTCHA, version 2. This version includes an "invisible" check that monitors multiple factors in the user's behaviour before making any kind of prompt.

Support for more CAPTCHA and challenge types (e.g. 2FA, honeypot) are roadmapped for future release.

Process Flow

This flow describes the standard Authenticate User Process from a high-level, "happy path" flow.

Authentication with Social Media

ULM also supports the option for a user to authenticate using a social media account that is associated to their ULM User ID. See the Onboard and Authenticate User with Social Account Process, Authentication Flow for more information.

App Settings

Certain aspects of the Process' behaviour are controlled by configurable application settings.

Note: All app settings are set within the MarketONE ULM Admin web application.

User Journey Flow Diagram

This diagram illustrates the standard user journey using the Authenticate Process.

This diagram also incorporates best practice routes to the Resend Verification and Activate User Processes.

API Walkthroughs

The following section provides guided walkthroughs of the Authenticate User Process, including demonstrations of the various branching paths the Process can take during its execution.

Basic Authentication Scenario

This is the simplest flow for the Authenticate User process. The Process consumes a valid authN ID and credential, and successfully authenticates the user. The Process then returns a successful response that indicates the user has been authenticated to ULM, and can proceed to make requests to protected APIs.

Initial Request

The Session Start API initializes the Process:

{
    "authnIdentifier": "father@operator.com",
    "credential": "letmein"
}

Request Parameters

Response

If the user provides valid credentials, and no other authentication protocols are necessary (e.g., 2FA) then the Process responds with an HTTP 200 status code, and user details in the body:

{
    "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
    "lastStep": true,
    "runtimeId": 229,
    "userId": 12345,
    "userAuthenticated:" true
}

Response Parameters

The client application can retain the user and runtime IDs to use MarketONE's ULM APIs to perform CRUD operations against those ULM entities.

Unverified Email/Mobile Response

If the user tries to authenticate with an unverified email or mobile, the Process simply resends an action token to that external channel, and then ends.

{
    "processId": "21d31975-583c-4ad5-aa3b-909386545032",
    "output": {
        "pkat": "d022a6c1-cc00-40f8-b5f2-74b03c7e5a61"
    },
    "lastStep": true
}

Any Process step that results in the sending of a ULM action token also returns a corresponding pkat to the client application. The client application should retain this information to render user options on the UI to trigger either the Activate User and/or Resend Verification Message Processes as needed.

Response Parameters

Basic Authentication Scenario with Invalid Credentials

This example repeats the basic scenario above, but includes bad user input in the first request.

Initial Request

The Session Start API initializes the Process:

{
    "authnIdentifier": "father@operator.com",
    "credential": "LetMeIn"
}

Request Parameters

Response: Operation Error

If the user provides invalid credentials, the Process responds with an HTTP 401 status code. The body includes an operationError array with the reason(s) as to what went wrong:

{
    "processId": "49819a56-5b81-49a0-8d26-2b39d7ce3859",
    "stepName": "StartStep",
    "operationError": [
        {
            "code": "authentication-required",
            "type": "com.uxpsystems.mint.framework.ulm.process.exception.LoginFailureException",
            "message": "Bad credentials"
        }
    ],
    "lastStep": false,
    "lastFailedStepAction": {
        "processId": "49819a56-5b81-49a0-8d26-2b39d7ce3859",
        "stepName": "ReEnterPrompt",
        "parameters": {
            "authnIdentifier": "String",
            "credential": "String"
        }
    }
}

Response Parameters

Re-Request: Fixed Credentials

Using the Process Step API, the client retries the request again with correct user credentials:

{
    "processId": "49819a56-5b81-49a0-8d26-2b39d7ce3859",
    "Parameters": {
        "authnIdentifier": "father@operator.com",
        "credential": "letmein"
    }
}

Request Parameters

Response: Successful

If the credentials have been validated successfully on this attempt, the API will respond indicating authentication is successful, as in the previous example:

{
    "processId": "49819a56-5b81-49a0-8d26-2b39d7ce3859",
    "lastStep": true,
    "runtimeId": 5049,
    "userId": 1,
    "userAuthenticated": true
}

Response Parameters

The client application can retain the user and runtime IDs to use MarketONE's ULM APIs to perform CRUD operations (e.g. GET /user/{userId}) against those entities.

About Max Retries: Each Process accepts a limited numbers of user input retry attempts before temporarily locking the user out, to avoid brute-force password attacks. If the limit is reached, the API will return this:

{
  "processId": "49819a56-5b81-49a0-8d26-2b39d7ce3859",
  "stepName": "ReEnterPrompt",
  "operationError": [
    {
      "code": "user-profile-locked",
      "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
      "message": "Your User profile has been disabled, Please try later"
    }
  ],
  "lastStep": false
}

The Max failed sign-in attempts app setting controls failed attempt limit. The default setting is 10 failed attempts. This setting is configured in the MarketONE User Admin web application.

Basic Authentication Scenario with reCAPTCHA

reCAPTCHA is a service provided by Google, and is integrated into a website through JavaScript code provided by Google themselves, with ULM accepting a verification token from reCAPTCHA (which ULM can independently verify through back-channel requests to reCAPTCHA APIs).

Request: Provide Credentials and reCAPTCHA Verification Token

The Session Start API initializes the Process, and the reCAPTCHA verification token is included as an additional field alongside the user's standard credentials.

{
  "authnIdentifier": "father@operator.com",
  "credential": "letmein",
  "recaptchaResponse": "any random value"
}

Request Parameters

Response: Success

The API will respond as normal, returning a successful authentication response if the credentials provided alongside the reCAPTCHA verification token are valid:

{
    "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
    "lastStep": true,
    "runtimeId": 229,
    "userId": 1,
    "userAuthenticated"
}

Response Parameters

Note: The client application can retain the user and runtime IDs to use the MarketONE ULM APIs to perform CRUD operations against those entities.

Error Codes

Below is a comprehensive list of potential error codes that may be returned during the execution of this Process.

Common Error Codes

ULM Core Process - Common Process Error Codes

Process Specific Error Codes

Revision History