Recover ID and Reset Password Processes

Content

• Overview
• Multiple Process Orchestration
• Process Flow
• App Settings
• Password Reset and Recovery User Journey
• API Walkthroughs
• Error Codes
• Revision History

Overview

In the event that a user misplaces and forgets their password, they can use their registered email address or mobile number to recover their User ID, and then set a new password to replace forgotten one. The full operation is orchestrated by two distinct but related Processes, because the user will need to navigate from the client UI to complete their journey.

Multiple Process Orchestration

Most user journeys are facilitated by a single Process. However, there are some cases where ULM orchestrates and links two or more Processes together to complete a given journey.

The Recover ID Process starts the user journey and sends a verification action token to a user's verified email address or mobile number. Once the user redeems that token with the GET session/token API, the API calls the Reset Password Process that then prompts the user set a new password.

Process Flow

This table describes the Process functionality at a high level.

App Settings

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

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

Password Reset and Recovery User Journey

This flow illustrates the standard user journey using the Password Reset and Password Recovery Processes.

This diagram also incorporates:

• A quick resend message option (PUT session/token)
• Long-form URL and short-form OTP verification options (GET session/token)

API Walkthroughs

The following section provides guided walkthroughs of the Recover ID and Reset Password Processes.

Recover ID Scenario

An anonymous user selects to recover their User ID via their only registered authN ID (email or mobile).

Initial Request

The Process Start API initializes the Process:

<no body>

Response: Prompt for AuthN ID

The Process responds with a request to provide a registered, email or mobile:

{
    "processId": "80d248a2-ec15-428f-be42-500426fabec9",
    "processName": "recovery.PasswordRecovery.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "authnIdentifier": "String"
    },
    "stepName": "UsernamePrompt",
    "lastStep": false
}

Response Parameters

Next Request: Provide user's AuthN ID

The user provides their AuthN ID, and the client passes it through the next Process Step API request:

{
    "processId": "80d248a2-ec15-428f-be42-500426fabec9",
    "parameters": {
        "authnIdentifier": "bob@example.com"
    }
}

Request Parameters

Response: Success

ULM delivers a notification to the email/mobile with a token and/or link which can be used to complete the password recovery. The Process ends, and returns a 200 HTTP status.

{
    "processId": "80d248a2-ec15-428f-be42-500426fabec9",
    "processName": "recovery.PasswordRecovery.v1.0",
    "lastStep": true,
    "output": {
        "pkat": "7c72281e-deb1-430c-be59-f3e0af71174d",
        "selectedRecoveryOptionType": "EMAIL",
        "selectedRecoveryOption": "b**@example.com"
    }
}

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 Reset Password Process.

The pkat is also required if the application wants to provide a quick verification message resend option on the UI, using the PUT /session/token?pkat={pkat} API.

Response Parameters

Note: Even if an invalid authN ID is supplied to the Process (no matching user exists within ULM), the Process will respond as if a notification has been sent. This is a security measure to prevent malicious actors from brute-force attempts to read read responses and determine valid authN IDs. ULM will not try to deliver notifications to users who do not exist. Instead, the Process silently fails.

Reset Password Scenario - Token URL

The user receives a recovery verification message in an email/SMS. The message includes a clickable/tappable link that is composed of two parts:

• A redirect URL back to the client application.
• The actual ULM action token appended to the end of the URL.

Initial Request: User Clicks Recovery Link

The user goes to their email/SMS and clicks the link. This directs their browser to the client application that takes the token value in the URL and passes it into the GET session/token API.

<no body>

If the token is valid, this API invokes the Reset Password Process.

Response: Prompt to Set New Password

The Process responds with a request for a new password:

{
    "processId": "de11cb72-c03b-423f-a6ed-4e13e2c6ddd2",
    "processName": "recovery.PasswordReset.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "newPassword": "String"
    },
    "stepName": "NewPasswordPrompt",
    "lastStep": false
}

Response Parameters

Next Request: User Provides New Password

The user supplies their desired new password, and the client passes it to the Process with the Process Step API.

{
    "processId": "de11cb72-c03b-423f-a6ed-4e13e2c6ddd2",
    "parameters": {
        "newPassword": "Sp4rinkl35"
    }
}

Request Parameters

Response: Success

If the password passes complexity validation, the Process completes its task and returns a 200 HTTP status code.

{
    "processId": "de11cb72-c03b-423f-a6ed-4e13e2c6ddd2",
    "processName": "recovery.PasswordReset.v1.0",
    "lastStep": true
}

The user must now use the new password set whenever they are prompted to provide it.

Response Parameters

Reset Password Scenario - OTP

The user receives a short-form custom One-Time Passcode (OTP) in an email/SMS. They must provide this OTP to the client application UI.

Initial Request

The user goes to their email/SMS and retrieves the OTP. They then enter the OTP into the client application. The application passes both the OTP and the PKAT into the GET session/token API.

<no body>

If both the OTP and PKAT are valid, this API invokes the Reset Password Process.

Response: Prompt to Set New Password

The Process responds with a request for a new password:

{
    "processId": "de11cb72-c03b-423f-a6ed-4e13e2c6ddd2",
    "processName": "recovery.PasswordReset.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "newPassword": "String"
    },
    "stepName": "NewPasswordPrompt",
    "lastStep": false
}

Response Parameters

Next Request: User Provides New Password

The user supplies their desired new password, and the client passes it to the Process with the Process Step API.

{
    "processId": "de11cb72-c03b-423f-a6ed-4e13e2c6ddd2",
    "parameters": {
        "newPassword": "Sp4rinkl35"
    }
}

Request Parameters

Response: Success

If the password passes complexity validation, the Process completes its task and returns a 200 HTTP status code.

{
    "processId": "de11cb72-c03b-423f-a6ed-4e13e2c6ddd2",
    "processName": "recovery.PasswordReset.v1.0",
    "lastStep": true
}

The user must now use the new password set whenever they are prompted to provide it.

Response Parameters

Error Scenario: Invalid Password

If the user provides an invalid new 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": "NewPasswordPrompt",
    "lastStep": false,
    "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].*"
        }
    ],
    "lastFailedStepAction": {
        "processId": "90163eaa-3d8a-4fa3-b2b5-100ea14b7a9f",
        "processName": "recovery.PasswordReset.v1.0",
        "displayMessage": "Please input required information",
        "parameters": {
            "newPassword": "String"
        },
        "stepName": "NewPasswordPrompt"
    }
}

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)

Reminder: 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.

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