Add/Update Email, Mobile, or Alias Process

Content

• Overview
• About AuthN IDs and Aliases
• Process Flow
• App Settings
• User Journey Flow Diagram
• API Walkthroughs
• Error Codes
• Revision History

Overview

This Process defines how an existing, authenticated either adds an additional authentication identifier (authN ID) to there ULM User ID, or updates (i.e., overwrites) an existing authN ID. Valid authN types include an email address or mobile number, and the authN must be verified before the user can use it for notification or authentication purposes.

This Process also includes support for adding non-verifiable user "aliases" that can be used for authentication with a password.

About AuthN IDs and Aliases

Authentication Identifiers (or authN IDs) are sometimes referred to as usernames. When a user onboards and authenticates into ULM, they supply an authN ID (email address or mobile number) and a password. An exception to this is when users onboard and authenticate using their social login account.

Every ULM User ID requires at least one verifiable email address or mobile number to be set as an authN ID. This includes the social onboarding scenario wherein the social provider returns an email address or mobile number.

ULM also supports the ability for users to add aliases to their User ID and to log in with them. For example, your business may wish to enable users to authenticate with a desired nickname, or short-form account number.

Note on Alias AuthN IDs: An alias is an authN ID with the following characteristics:

• It is an alphanumeric string
• It has a minimum of 6, and maximum of 16, character limit
• Its pattern must be distinct from an email address or mobile number pattern
• It has no entity status because it cannot be verified like an email address or mobile number
• It is unique across all user authN IDs in ULM (i.e., no two users can use the exact same alias)

Aliases cannot be verified like an external contact channel. Therefore, a user who adds an alias to their User ID can use it in the Authenticate User Process right away. However, in order to be able to add an alias to their User ID, the user must first have at least one registered, verified authN ID.

In order for users to be able to add aliases, valid alias pattern must be set in the ULM Admin UI web application, under the application Settings menu. This is the same location where valid email and mobile pattern rules are set as well.

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.

User Journey Flow Diagram

This flow diagram illustrates the standard user journey using the Add or Update User Email/Mobile Process.

Note: This diagram also incorporates user authentication, and the Resend Verification and Activate User Processes.

API Walkthroughs

This section provides guided walkthroughs of the Add/Update Email, Mobile, or Alias Process process, including demonstrations of the various branching paths the Process can take during its execution.

Add New AuthN ID Scenario (Email or Mobile)

In this flow, an authenticated user adds a new email or mobile to their User ID, independent of any existing authN IDs on the User ID.

Initial Request

The POST /process/start/{processName} API initializes the Process:

Response

The Process responds with a request for information:

{
    "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
    "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "newAuthnIdentifier": "String",
        "oldAuthnIdentifier": "String"
    },
    "stepName": "AddOrUpdateAuthnIdentifierPrompt",
    "lastStep": false
}

Response Parameters

Next Request: Provide New authN ID

The user enters their desired authN ID and the client passes that info to the Process with the Process Step API.

{
    "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
    "parameters": {
        "newAuthnIdentifier": "john@example.com"
    }
}

Request Parameters

Response: Success

If the new authN ID does not match an existing authN ID already assigned to the user (or any other ULM User ID), the Process completes its task and returns a 200 HTTP status code. The Process also sends an action token to the user through email or SMS.

{
    "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
    "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
    "lastStep": true,
    "output": {
        "newAuthnIdentifier": {
            "id": 3,
            "status": "activating",
            "value": "john@example.com"
        },
        "attributeName": "emails",
        "pkat": "4c6fd6cd-78a7-487d-b746-2628a77a0131"
    }
}

OTP Verification & 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.

If the new authN ID is an email or mobile, the user cannot use it for authentication purposes until they activate (verify) it. If the new authN ID is an alias, the user can user it right away.

Update Existing AuthN ID Scenario

In this flow, an authenticated user overwrites an authN ID that already exists on their User ID.

Initial Request

The Process Start API initializes the Process:

Response

The Process responds with a request for the authN ID(s):

{
    "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
    "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
    "displayMessage": "Please input required information",
    "parameters": {
        "newAuthnIdentifier": "String",
        "oldAuthnIdentifier": "String"
    },
    "stepName": "AddOrUpdateAuthnIdentifierPrompt",
    "lastStep": false
}

Response Parameters

Next Request: Provide Replacement AuthN ID

A response is crafted with input from the user:

{
    "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
    "parameters": {
        "oldAuthnIdentifier": "john@contoso.com",
        "newAuthnIdentifier": "john@example.com"
    }
}

Request Parameters

Note: The new and old authN IDs must have the same format (i.e., the user cannot update an existing email address with a mobile number, or vice versa).

Response: Success

If the new authN ID does not match an existing authN ID already assigned to the user (or any other ULM User ID), the Process completes its task and returns a 200 HTTP status code. The Process also sends an action token to the user through email or SMS.

{
    "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
    "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
    "lastStep": true,
    "output": {
        "newAuthnIdentifier": {
            "id": 3,
            "status": "activating",
            "value": "john@example.com"
        },
        "oldAuthnIdentifier": {
            "value": "john@contoso.com"
        },
        "attributeName":"emails",
        "pkat": "4c6fd6cd-78a7-487d-b746-2628a77a0131"
    }
}

OTP Verification & 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

Note: The old authN ID remains fully activated until the user verifies the new authN ID.

Error Scenario: Desired AuthN ID is Already in Use

This step may return errors if the Authentication Identifier provided already exists within ULM, either assigned to the current user or to any user. Below is an example of the response received when the Authentication Identifier already exists:

{
    "processId": "56a248cd-a14f-421d-a9c1-1220de53848f",
    "lastStep": false,
    "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
    "operationError": [
        {
            "code": "already-exist-authn-identifier",
            "type": "com.uxpsystems.mint.framework.ulm.process.service.ServiceStep.GeneralFailure",
            "message": "newAuthnIdentifier already exists",
            "authorities": [
                {
                    "authority": "ROLE_USER"
                }
            ]
        }
    ],
    "stepName": "AddOrUpdateAuthnIdentifierPrompt",
    "lastFailedStepAction": {
        "processId": "56a248cd-a14f-421d-a9c1-1220de53848f",
        "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
        "displayMessage": "Please input required information",
        "parameters": {
            "newAuthnIdentifier": "String",
            "oldAuthnIdentifier": "String"
        },
        "stepName": "AddOrUpdateAuthnIdentifierPrompt"
    }
}

Error Response Parameters

Note: The user is free to retry after checking their spelling, or changing the desired authN ID value.

Error Codes

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