Onboard User with Email and Mobile Process

Content

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

Overview

ULM cloud uses the user's supplied email address or mobile number as the basis for User ID creation. The email/mobile is registered as an unverified authentication identifier (or authN ID) that subsequently needs to be verified by the Activate User Process before the user can Authenticate into the service.

Note: Front-end human actors that interact with the system are noted as users with a lowercase "u." User IDs or ULM User entities are noted with an upper case "U."

Process Flow

This table describes the Onboard with Email/Mobile Process from a high-level, "happy path" flow.

App Settings

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

Note: All app settings are set in the MarketONE ULM Admin web application. System managers and administrators can consult the MarketONE User Admin UI User Guide.

User Journey Flow Diagram

This flow diagram illustrates the standard user journey using the Onboarding w/Email or Mobile Process.

Note: 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 Onboard User with Email/Mobile Process.

Onboard User with Email Scenario

This is the most conventional user onboarding flow. The Process consumes the user's email address and password, creates a new unique ULM User entity, and then registers the submitted email as an attribute and authentication identifier (authN ID) on that entity. Both the ULM User and the authN ID attribute are created with an activating status, pending verification.

Initial Request

The Process Start API initializes the Process:

<no body>

Response

The Process responds with a request for user information:

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "processName:" "onboard.OnboardUserWithEmailMobile.v1.0"
    "displayMessage": "Please Enter User details for self onboarding",
    "parameters": {
        "email": "String",
        "phone": "String",
        "credential": "String",
        "firstName": "String",
        "lastName": "String",
        "displayName": "String",
        "lang": "String"
    },
    "stepName": "UserDetailsPrompt",
    "lastStep": false
}

The application can leverage this information to render the actual sign-up form on the UI.

Response Parameters

Next Request: Provide User Details

Using the Process Step API, the client passes the user-supplied info to the Process.

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "parameters": {
        "credential": "GoodPas$word123",
        "email": "bob@example.com"
    }
}

Request Parameters

Response: Success and User Creation

If the email and password pass validation, the Process completes its task and returns a 200 HTTP status code. The Process also sends an action token out to the user's email address in the form of a clickable verification link.

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "processName": "onboard.OnboardUserWithEmailMobile.v1.0",
    "output": {
        "pkat": "sdfsd-gfsdfgsd-sdgsdg-sfddsf-dsfsdf",
    },
    "lastStep": true
}

OTP Verification and Resend Verification

Any Process step that sends a ULM action token also returns a corresponding pkat to the client application. In order to enable OTP verification on the UI, the client must retain the pkat returned by the final Process step. The pkat, along with the user supplied OTP, is required for the GET /session/token?customToken={OTP}&pkat={pkat} API to invoke the Activate User Process.

In cases where the user is anonymous, the pkat is required if the application wants to provide a quick token resend option on the UI, using the PUT /session/token?pkat={pkat} API. This method applies to cases where the user is anonymous (i.e., they are not authenticated in ULM). However, if the user is currently authenticated in ULM, the client application can instead invoke the Resend Verification Process for this purpose.

Response Parameters

The user has successfully onboarded with their email address.

Onboard User with Mobile Scenario

The flow is similar to the Email Onboarding flow above, except the verification action token is sent to the user over SMS, and it is sent as a short-form OTP. The user needs to manually supply that OTP to the UI for verification.

The Process consumes the user's mobile number and password, creates a new unique ULM User entity, and then registers the submitted mobile as an attribute and authentication identifier (authN ID) on that entity. Both the ULM User and the authN ID attribute are created with an activating status, pending verification.

Initial Request

The Process Start API initializes the Process:

<no body>

Response

The Process responds with a request for user information:

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "processName:" "onboard.OnboardUserWithEmailMobile.v1.0"
    "displayMessage": "Please Enter User details for self onboarding",
    "parameters": {
        "email": "String",
        "phone": "String",
        "credential": "String",
        "firstName": "String",
        "lastName": "String",
        "displayName": "String",
        "lang": "String"
    },
    "stepName": "UserDetailsPrompt",
    "lastStep": false
}

Note: The application can leverage this information to render the actual sign-up form on the UI.

Response Parameters

Next Request: Provide User Details

Using the Process Step API, the client passes the user-supplied info to the Process.

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "parameters": {
        "credential": "GoodPas$word123",
        "phone": "4161234567"
    }
}

Request Parameters

Response: Success & User Creation

If the mobile and password pass validation, the Process completes its task and returns a 200 HTTP status code. The Process also sends an action token out to the user's mobile number.

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "processName": "onboard.OnboardUserWithEmailMobile.v1.0",
    "output": {
        "pkat": "sdfsd-gfsdfgsd-sdgsdg-sfddsf-dsfsdf",
    },
    "lastStep": true
}

OTP Verification and Resend Verification

Any Process step that sends a ULM action token also returns a corresponding pkat to the client application. In order to enable OTP verification on the UI, the client must retain the pkat returned by the final Process step. The pkat, along with the user supplied OTP, is required for the GET /session/token?customToken={OTP}&pkat={pkat} API to invoke the Activate User Process.

In cases where the user is anonymous, the pkat is required if the application wants to provide a quick token resend option on the UI, using the PUT /session/token?pkat={pkat} API. This method applies to cases where the user is anonymous (i.e., they are not authenticated in ULM). However, if the user is currently authenticated in ULM, the client application can instead invoke the Resend Verification Process for this purpose.

Response Parameters

Error Scenario: Invalid Credentials

If the user provides an invalid password, the Process responds with a HTTP 400 status code.

The body includes a fieldErrors array with the reason(s) as to what went wrong:

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "stepName": "UserDetailsPrompt"
    "fieldErrors": [
        {
            "field": "credential",
            "code": "NotWeakPassword",
            "rejectedValue": "test",
            "message": "password-regex-rule-violation-.*[0-9].*"
        },
        {
            "field": "credential",
            "code": "NotWeakPassword",
            "rejectedValue": "test",
            "message": "blacklisted-password"
        },
        {
            "field": "credential",
            "code": "NotWeakPassword",
            "rejectedValue": "test",
            "message": "password-regex-rule-violation-.{8,}"
        },
        {
            "field": "credential",
            "code": "NotWeakPassword",
            "rejectedValue": "test",
            "message": "password-regex-rule-violation-.*[A-Z].*"
        }
    ],
    "lastStep": false,
    "lastFailedStepAction": {
        "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
        "displayMessage": "Please Enter User details for self onboarding",
        "parameters": {
                "email": "String",
                "phone": "String",
                "credential": "String"
        },
        "stepName": "UserDetailsPrompt"
    }
}

In the above example, the fieldErrors array indicates the following:

• The password fails to include at least one number (0-9)
• The password is on an internal list of commonly banned passwords
• The password fails to meet the minimum length of (8 characters)
• The password fails to include at least one capital (A-Z)

Note: Rules are configured under the Password Complexity Rules setting in the MarketONE ULM Admin UI.

The Process also includes a lastStepFailedAction object that repeats the previous Process step's request. The user can re-attempt their request with a different (ideally stronger) password, and complete their onboarding as normal.

Error Response Parameters

Error Scenario: AuthN ID is Already in Use

If the user provides an authN ID that already exists in ULM, the Process responds with an HTTP 401 status code. The response body includes an operationError array with the reason(s) as to what went wrong:

{
    "processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "stepName": "UserDetailsPrompt"
    "lastStep": false,
    "operationError": [
        {
            "code": "already-exist-phone",
            "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
            "message": "Failed to create a user with duplicated phone number",
            "authorities": [
                {
                    "authority": "ROLE_ANONYMOUS"
                }
            ]
        }
    ],
    "lastFailedStepAction": {
        "processId": "b02ad80c-6116-408c-b03b-e4a32852dd41",
        "processName": "onboard.OnboardUserWithEmailMobile.v1.0",
        "displayMessage": "Please Enter User details for self onboarding",
        "parameters": {
            "credential": "String",
            "phone": "String",
            "displayName": "String",
            "lang": "String",
            "email": "String"
        },
        "stepName": "UserDetailsPrompt"
    }
}

Additionally, the Process includes a lastStepFailedAction object that repeats the previous Process step's request. The user can make sure they entered the correct authN ID, retry their request, and complete the Process as normal.

Error Response Parameters

Error Codes

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

Common Error Codes

Common Process Error Codes

Process-Specific Error Codes

Revision History