ULM Action Tokens

Content

Overview

Some user journeys are easily facilitated by a single Process or standard REST API. Conversely, there are some cases where ULM Cloud needs to orchestrate and link two or more dependent Processes in order to complete a given journey. To do this, the Process framework leverages action tokens in order to link Processes together.

How Tokens Work

An action token is a unique one-time use token that triggers a one-time action when redeemed. Tokens are context-aware so that, upon token redemption:

  • ULM Cloud knows what task (Process) needs to be performed on what resources
  • ULM Cloud knows who is redeeming the token, even if no current ULM user session exists

For example, a standard email-driven onboarding journey starts with the Onboard User with Email and Mobile Process that consumes and validates a new user's information (e.g., email address, password), creates the new User ID, and persists that User ID to ULM Cloud's data store. The Process also sends a verification message to that user's email address with an clickable verification link. The user then needs to navigate to their email and click the link to trigger the Activate User Process.

To achieve this, ULM issues an action token at the end of the first Process, and sends that token to the user-submitted contact channel (email address or mobile number). The token is contextually aware of both the user and the contact channel in question, and this allows the second Process to complete its task without any ambiguity when the token is redeemed.

Other common use cases with dependent Processes and action tokens include:

  • Recovering lost passwords: A anonymous user forgets their password and invokes the Recover ID Process. ULM Cloud sends a token to the user's email address or mobile number, and the user then uses that token to trigger the Reset Password Process.
  • Adding new authentication identifiers: An authenticated user adds a new email or mobile to their user ID with the Add/Update Email, Mobile, or Alias Process. ULM Cloud sends a token to the new email/mobile for verification. The user then uses that token to trigger the Activate User (and User Attribute) Process.
  • Sharing accounts and services: An authenticated user selects to share their account or service with another person. To do this, they submit the invitee's email or mobile to the Share Account, Subscription, or Feature Process. ULM then sends an action token to the supplied email/mobile. The invitee clicks the invitation link (token) to trigger the Accept or Decline Service Invitation Process.

This is a select sample of common cases. As Amdocs continues to develop new user lifecycle management Processes, tokens are included to facilitate multi-Process user journeys with multiple entry points.

Token Formats and Notification Settings

Whenever ULM Process issues an action token, it is rendered and delivered in one of two different formats:

Token URL

A long-form, redirect URL that, when clicked, sends the user back to your client application, whereupon the application then calls the GET /session/token API to invoke the dependent Process.

The token URL is composed to two separate pieces of information:

  • A redirect URL that that leads the user from their email/SMS back to the client application. This URL is defined as an Process-specific app setting in the ULM Admin web application.
  • The long-form actual token ID. When a Process completes, it automatically generates the token value and appends it to the redirect URL that is sent to the user.

Token URLs are arguably easier for end users to complete their user journey, in that they only need to click (or tap, if the link is send over SMS) the link to redeem the action token and trigger the next Process.

Token URLs have a default lifespan of 10080 minutes (7 days) before they expire. This lifespan can be configured on the app Settings menu in the ULM Admin web application.

One Time Passcode (OTP)

This is a short-form (6 number) code that represents the actual token value. When the user receives the code, they then need to supply that code to the client application UI. The application then calls the GET /session/token API to invoke the dependent process.

Token OTPs have the benefit of a quick and immediate verification step. The user simply retrieves the OTP from their SMS or email, and then punches the number into the client UI.

OTPs have a lifespan of 5 minutes before they expire. This lifespan cannot be configured. Therefore, it is useful to leverage the Resending Tokens options in cases where the user allows the token OTP to expire.

Using ULM Notification Service

With out-of-the-box default settings, most ULM Processes send both a long-form clickable link and a short-form custom OTP out to the selected contact channel, regardless of that channel type. ULM Cloud can control what token types are sent over what channel based on HTML & CSS templates stored in the ULM Cloud data store. These templates determine the content of the notification (messaging, branding) as well as the token type (link, OTP, or both) based on the user's channel type (email or mobile).

These templates are set according to your business requirements during the initial onboarding and integration phase between your business and ULM Cloud. For example, as a best practice, you can opt to send only clickable links through email notifications and only OTPs through SMS.

Leveraging Your Business' Own Notification System

Amdocs also provides a MarketONE CSP Adapter API for large-scale Service Providers who want to leverage their existing notification system. Whenever a user completes a Process, ULM Cloud can send all of the relevant content (user information, redirect+token URL, custom token OTP) to your own notification delivery system via this API. Your service can then construct and send the desired notifications to the user's contact channel.

Whether your business is using ULM Cloud's notification templates or your own existing notification system, be sure to confirm what types of action tokens that system is sending to end users, and build your client application screens accordingly. For example, if you're only sending clickable links to your end users, then you do not need to worry about providing any kind of OTP verification. Conversely, if you're only sending OTP over one channel, but both a link and OTP over another, then you'll want to make sure each channel-driven flow is accounted for on your UI(s).

Resending Tokens

There are use cases where ULM Cloud needs to resend an action token to a user upon request.

For example, a newly onboarded user forgets to validate their email address or mobile number until a later date, several hours or days beyond the token expiration period. Alternatively, the user accidentally deletes or misplaces their message. In either case, the user then needs to request a message resend.

Some of the common token resend scenarios include:

  • Signing in with an unverified authN ID: An anonymous user attempts to sign in with an unverified email or mobile. The Authenticate User Process consumes and confirms that the authN ID has an activating status, and automatically sends a new verification message.
  • Requesting a resend (authenticated): An authenticated user selects to add an additional email address to their User ID. The Add/Update Email, Mobile, or Alias Process consumes the new email, and then sends a token (as a clickable link) to that email. The application then displays a "Pending" or similar message next to the email listed in the user's profile, and a Resend button. The user selects Resend, and the application invokes Resend Verification Message Process with the email address in the API request URL:

    POST {url}/process/start/userManagement.SendVerification.v1.0?authnIdentifier={email address}
  • Requesting a resend (anonymous): A new, anonymous user completes their onboarding with a mobile number. ULM sends a token (as a short OTP) over SMS. The application presents a post-onboarding screen with a field to enter the OTP, and a Resend button. The user selects Resend, and the application then invokes the PUT /session/token API:

    PUT {url}/session/token?pkat={pkat}

If a client application needs to facilitate a quick Resend function or OTP validation option on the UI, then it must retain and leverage the pkat that is returned from a Process. See directly below for more information.

Proof Key for Action Token (PKAT)

Any Process that results in the issuance of a ULM action token also returns a key item in its final API Step response to the client application: a pkat, or Proof Key for Action Token.

Proof Key for Action Token 
"processId": "8bca30ca-dd44-4050-aece-53b0dbed1922",
    "returnParameters": {
        "pkat":"sdfsd-gfsdfgsd-sdgsdg-sfddsf-dsfsdf"
        }
    }

The client UI should retain the pkat to facilitate OTP verification and/or a quick "resend" option on the UI.

Short OTP Verification (Activate User Process)

If a user receives an OTP, then they need to manually provide that OTP to the application. The application then needs to invoke the GET /session/token API with both the OTP and pkat in the API request URL:

GET {url}/session/token?customToken={otp}&pkat={pkat}

OTP tokens, while convenient for users, could be targeted by brute-force software that continuously tries all combinations. The PKAT provides additional protection, as it must be provided for a valid request.

Quick Token Resend

If you want your application to provide an anonymous user with a quick "Resend" option at the end of a given Process, then the UI can invoke the PUT /session/token?pkat={pkat} Process API with the pkat in the API request URL:

PUT {url}/session/token?pkat={pkat}

This API is similar to – but distinct from – the Resend Verification Message Process. The Resend Process is invoked from an authenticated state; it invalidates an existing token and sends a new one to the user. Conversely, PUT /session/token is invoked from an anonymous state, and it simply resends the existing token.

Sequence Diagrams

Onboarding and Activation

This sequence diagram illustrates an end-to-end onboarding user journey with an action token:

Add New Email, Resend Verification, and Activation

This sequence diagram illustrates an add new email user journey with expired and reissued tokens:

Revision History

Version Description
2020.09 Added this topic.