Resend Verification Message Process

Content

• Overview
• Multiple Process Orchestration
• Resend Process vs Resend API
• Add the AuthN ID to the Request URL
• ULM User Entity and AuthN ID Status
• Process Flow
• App Settings
• API Walkthrough
• Error Codes
• Revision History

Overview

This Process defines how an authenticated user requests to send a verification message to an unverified email address or mobile number.

Multiple Process Orchestration

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

The Resend Verification Process is a connective Process that links a preceding and subsequent process as a part of a larger journey.

Resend Process vs Resend API

This process is functionally similar to – but distinct from – the PUT session/token API. See the following table for more details:

The key things to remember are that when the Resend Verification Process issues and sends new action token to the user, this means that the new token has a new expiration period. Conversely, when the PUT session/token API resends an existing token, that token's original expiration period still applies.

Additionally, the Resend Verification Process does not require a PKAT that the PUT /session/token requires.

Add the AuthN ID to the Request URL

Like most Processes, this Process is initialized by the Process Start API. The Process Start API optionally consumes no payload, and will respond with a request for the data it requires to finish its task. However, the client can add the required parameters upfront in the initial API request URL, if it has access to that data.

For example, in the Onboard & Authenticate User with Social Account Process, invoking the Process as normal will return a request for a valid providerId in the next Process Step request. However, the client can provide the providerId in the request URL to skip the initial step:

• POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0?providerId=facebook

With regards to the Resend Verification Message Process, the target authN ID (i.e., the email or mobile to which the message will be sent) must be included as a request parameter the API URL.

ULM User Entity and AuthN ID Status

ULM is built on top of a user-centric and entitlement-specific data model comprised of ULM data entities. Each entity is defined by a set of default and extensible attributes. Some attributes are simple string values, and others are more complex arrays (i.e., list of values that make up a single attribute).

When a user authenticates into the client application, the client UI can invoke the GET /user API to retrieve the ULM User entity from ULM Cloud data store. All of a user's registered authN IDs are stored in the attributes object, and this includes the respective status of each authN ID:

{
  "attributes": [
    {
      "name": "emails",
      "value": [
        {
          "id": 4567,
          "email": "jane.smith@email.com",
          "label": "personal email",
          "status": "activated"
        },
        {
          "id": 8910,
          "email": "jane_s@WorkCorp.com",
          "label": "work email",
          "status": "pending"
        }
      ]
    },
    {
      "name": "mobiles",
      "value": [
        {
          "id": 1234,
          "country": "canada",
          "label": "work phone",
          "number": "416-555-9999",
          "status": "activating"
        }
      ]
    },
    {
      "name": "favouriteFood",
      "value:" "sushi"
    }
  ],
  "id": "808",
  "status": "activated",
  "type": "com.uxpsystems.ulm.user.RegularUser",
}

The client UI can leverage this API to retrieve the status of each authN ID and display that status on the user's own profile within the application, if required.

Process Flow

This table describes the Process on a high level.

App Settings

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

API Walkthrough

The following section provides a guided walkthrough of the Resend Verification Message Process.

Send New Verification Scenario

An authenticated user selects to send a verification message to either an e-mail address or phone number, as they may have misplaced or accidentally deleted the previous one. The email/mobile is registered to this user, but it still has an activating or pending status.

Request

The Process Start API initializes the Process. The target authN ID must be provided in the request API URL:

<no body>

Response

If the target authN ID is valid, then 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": "501da7c2-77c5-4a2f-a83b-2ddb62f186c0",
    "processName": "userManagement.SendVerification.v1.0",
    "lastStep": true,
    "output": {
        "pkat":"c053fb7e-5efb-4876-b2f3-944790223e2c"
    }
}

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: AuthN ID Not Provided

If this Process is invoked without a valid authN ID in the request URL, then the Process responds with a HTTP 400 status code. The body includes a operationError array with the reason(s) as to what went wrong:

{
    "operationError": [
        {
            "code": "authn-identifier-not-found",
            "type": "com.uxpsystems.mint.framework.commons.exception.PlatformException",
            "message": "Requested authentication identifier cannot be verified",
            "authorities": [
                {
                    "authority": "ROLE_USER"
                }
            ]
        }
    ],
    "processId": "6989418a-cc77-47cf-8a0d-589f4af9d28d",
    "lastStep": false,
    "processName": "userManagement.SendVerification.v1.0",
    "stepName": "StartStep"
}

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 Code

Common Process Error Codes

Process-Specific Error Code

Revision History