Standard User Authentication

Content

• Overview
• User Authentication Scenario
• User Session Cookies
• ULM Process API
• Further Reading
• Revision History

Overview

This topic outlines the basics of ULM user authentication (more commonly called user sign-in or user login).

User Authentication Scenario

A typical user authentication scenario follows a standard flow:

1. An end user provides their authentication identifier (or authN ID) and password to the client.
2. The client passes that data in a POST /session/start API. This API invokes the Authenticate User Process.
3. (Conditional) The end user passes additional security protocols (e.g., MFA, reCAPTCHA), if any.
4. ULM Cloud validates the end user's credentials, and opens a user session.
5. A JSESSIONID token and remember-me token are returned in the API response.
6. The end user's browser stores both tokens as browser cookies.

On the surface, authentication looks like a simple REST API call that consumes the user's credentials. In a "happy path" flow, this is true from the end-user's perspective. However, as a ULM Process, the Authenticate User Process also supports optional security protocols, such as Multi-Factor Authentication (MFA) and CAPTCHA to ensure safe and seamless user authentication.

User Session Cookies

Once a user successfully authenticates with ULM, the browser stores a JSESSIONID token and an optional remember-me token (called the mint-sso-token) returned in the API call.

JSESSIONID

JSESSIONIDs are generally short-lived (between minutes and hours) and do not persist between browser windows, devices, or other session demarcation points.

Remember-me

Remember-me tokens, conversely, are long-lived tokens (between hours, days, and even months) that are used to transparently recreate a user's session without the need for the user to authenticate again.

Remember-me tokens are optional. If a remember-me token is provided alongside a JSESSIONID, the remember-me token always takes precedence. In other words, if an expired JSESSIONID is provided alongside a valid remember-me token to any REST API, then that API uses the remember-me token to create a new user session and return a new JSESSIONID to the browser. Similarly, if a valid JSESSIONID is provided but does not match the session identifier in a provided remember-me token, then the current session is destroyed and a new session created in its place, with a new JSESSIONID returned that matches the remember-me token.

In any instance that a remember-me token is used to construct a new session, the system invalidates that particular remember-me token and issues a new one. This is a security measure to prevent cookie theft attacks from obtaining reusable authentication tokens.

ULM Process API

An end user authenticates into ULM by way of the POST /session/start API (also known as the Session Start API). This API invokes the Authenticate User Process that consumes the users credentials, verifies who they are, and opens the user session.

Request

POST http://~your.url/rest/{version}/session/start

{
   "authnIdentifier":"jane_smith@email.com",
   "credential":"pL3a$eLetM3!n"
}

Request Parameters

Response

{
   "processId":"eec918ff-5db4-4fee-a601-5ff76a099c8e",
   "lastStep":true,
   "runtimeId":229,
   "userId":12345,
   "userAuthenticated":true
}

Response Parameters

The steps above outline the most basic, straightforward "happy path" of this Process. It can also take different "paths" and incorporate alternate steps; this depends on a combination of system settings, user input, and whether or not additional authentication protocols (e.g., Multi-Factor Authentication (MFA), CAPTCHA) are enabled. Consult the Authenticate User Process topic for a full comprehensive overview of this Process, including multiple user scenarios with step-by-step API walkthroughs.

Once the end user is authenticated, ULM User details can be obtained via the GET /user API.

The end user can close their session with the POST /session/end API (with no payload). This invalidates both the current session (identified by the JSESSIONID cookie) and any issued remember-me tokens. will not invalidate any other sessions the end user may have.

Note: Access to any protected REST API requires, at a bare minimum, a valid JSESSIONID token.

See the ULM APIs in the MarketONE Developer Portal for the full API spec.

Further Reading

If you're new to ULM Cloud or ULM Processes, be sure to first read the ULM Cloud Process Guide section for comprehensive information on how each Process is executed, before attempting to test out the ULM API spec.

Revision History