Social Media User Authentication

Content

Overview

As an alternative to a standard username and password login, ULM users can authenticate themselves using a social media profile that is associated to their ULM digital user ID. Supported social providers follow the OAuth2 Authorization Framework Specification.

Social Media Authentication Scenario

The social media authentication scenario follows a standard flow:

  1. A user selects their preferred social media on the UI login page.
  2. The UI calls the Onboard and Authenticate User with Social Account Process.
    Note: Like most ULM Processes, this Process is invoked using the POST /process/start/{processName} API.
  3. The browser redirects to the selected social provider, and the user authenticates with that service.
  4. The social provider prompts the user to accept OAuth scopes (e.g. "ULM needs your email, name" etc).
  5. The user accepts.
  6. The social provider redirects them back to ULM, with an OAuth authorization code stored in the URL.
  7. ULM performs a backend call to the social provider and exchanges the Oauth authorization code for an access token and refresh token. These tokens signify to ULM that the user is authenticated.
  8. ULM creates a user session, and stores a JSESSIONID and Remember-me token in the user's browser.

Subsequent authentication calls to the same social provider will usually skip steps 4 and 5, because social provider remembers the user's previous consent. If the provider forgets that consent, then the user will need to re-consent to sharing their details with ULM Cloud.

Note: ULM supports four social account providers out of the box: Facebook, Google, AppleID, and LinkedIn. Each provider must be independently configured in the ULM Admin web application UI with a customer-specific client token and secret, obtained from the social provider itself for the purposes of OAuth2 authorization. The social provider functionality will not be functional if these settings are not configured.

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).

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

Social authentication is handled by the Onboard and Authenticate User with Social Account Process. This Process is initiated by the POST /process/start/{processName} API request and, if required, continued and completed with subsequent PUT /process/step API requests.

The Process is designed to responsively handle a variety of use cases. It can go in different "paths" depending on:

  • Whether or not the end user already has a ULM User ID.
  • What social providers are enabled on the MarketONE ULM Admin web application.
  • Whether or not the specific social provider is provided in the initial request.
  • Whether or not the end user's ULM User ID (if any) is associated to the selected provider.
  • The user data returned from the social provider.
  • The decisions that the end user makes if and when they are prompted to confirm data from the provider.

See the Onboard and Authenticate User with Social Account Process topic for a full comprehensive overview of this Process, including conceptual information (OIDC 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

Version Description
2020.11 Added this topic.