Authenticate users in a microsite

Learn how to set up user authentication for the Loyalty Microsite, covering integrated and embedded options for seamless user login with your existing app or website credentials.

About authentication in the Loyalty Microsite

User authentication enables users to sign up, log in, and access the Loyalty Microsite. There are two main authentication approaches:

Embedded authentication

This option allows users to sign up and log in using your existing app or website flow. Users are automatically logged in to the microsite using the same credentials they already use on your platform, creating a seamless and transparent experience.

Interactive authentication

In this option, users create a dedicated account for the Loyalty Microsite, using a separate sign-up and login flow specifically for the loyalty program.

---

Embedded authentication

With embedded authentication, users sign up and log in through your existing authentication flow. When they access the microsite, a session is created for them automatically. This avoids creating duplicate accounts or requiring an additional login.

To ensure users are authenticated transparently, session tokens are used. There are two options for passing the session token:

• Session Token in URL The session token is appended directly to the URL query parameter, which loads the microsite in a logged-in state.

• Session Cookie The session token is stored as a cookie in the user’s browser, shared across both the microsite and the main website for automatic login.

Creating the user’s session token

To initiate a user’s session in the microsite without requiring manual login, you’ll need to send an HTTP request from a secure server-side context with the user’s details to https://MICROSITEURL.COM/api/auth.

This request accomplishes two things:

1. Authenticates the User: It specifies the user to authenticate (via the selector.authIdentifier property).

2. Updates Profile Information: If the user already has an account, their profile details are updated with the data in the request. If no account exists, the microsite will create one in the Loyalty Engine just in time based on the provided data.

3. Optionally sets (overwrites) their points balance: if relevant for your use case you can define a new amount to which the user's points balance should be set.

Required Parameters

Include the following fields in the request:

• X-Client-ID header: Identifies the requester.

• selector.authIdentifier: Matches the pre-existing user identifier used in your website or app session.

• profile Fields: emailAddress, givenName, and familyName (mandatory); other fields are optional but recommended for a more tailored user experience.

Optional Parameters

• points: a new value for the user's point balance which will overwrite any pre-existing balance.

This method is an upsert process, meaning it creates a new user if none exists, or updates the profile if the user already exists.

This HTTP request should be made from a secure server-side context.

It should not be made from a client-side context since that would expose the X-Client-ID which could then enable a malicious actor to impersonate a user if they knew the user's ID.

Request Example

POST /api/auth HTTP/1.1
Host: https://MICROSITEURL.COM
Content-Type: application/json
Accept: application/json
X-Client-ID: CLIENT-ID-HERE
{
 "selector": {
   "authIdentifier": "USER-IDENTIFIER-HERE"
 },
 "profile": {
   "givenName": "Jane",
   "familyName": "Doe",
   "emailAddress": "[e-mail]",
   "gender": "FEMALE",
   "birthdate": "1980-01-01",
   "country": "GB",
   "city": "Leeds",
   "postcode": "LS1 5PZ",
   "pictureUrl": "https://example.com/pic.jpg",
   "streetAddress": "99 Road Street",
   "region": "West Yorkshire",
   "telephoneNumber":  "01437532699"
 },
 "points": 123
}

Response Example

HTTP/1.1 200 OK
Set-Cookie: session=p%2B6BqjiOhRvKvD0DxX632%2FAEiZExMAAY4AEQR1qt%2Bhr1nRLdoxuTrS01kecZjPsyMwGQ6GoyiaQvxW%2BNLXWnrYdeWoIoemeg0RU2qkEn4A%3D%3D; Max-Age=259200; Domain=customer.web.wlloyalty.net; Secure; SameSite=None
Content-Type: application/json; charset=utf-8
Content-Length: 384
{
  "status": "success",
  "data": {
    "user": {
      "externalIdentifier": "5b2257d404e0e30bf729cbf2"
      "authIdentifier": "5b2257d404e0e30bf729cbf2",
      "isRestricted": false,
      "id": "d9d35027-58e3-4167-8e22-a81728f46f62",
      "createdAt": "2018-07-20T09:19:54.699Z",
      "updatedAt": "2019-08-21T10:22:48.017Z",
      "flags": {
        "genderProvided": true
      }
    },
    "session": "p+6BqjiOhRvKvD0DxX632/AEiZExMAAY4AEQR1qt+hr1nRLdoxuTrS01kecZjPsyMwGQ6GoyiaQvxW+NLXWnrYdeWoIoemeg0RU2qkEn4A=="
  }
}

Activating the user's session

Upon a successful request, the response body will contain the session token within the session property. To use this token for automatic login in the microsite, you can either:

1. Append the Session Token to the URL as a query parameter

2. Set the Session Token directly as a Cookie

Selecting an approach

The query parameter method is ideal when opening the microsite in a new window or tab after authenticating the user on your own website. This approach is straightforward but requires an initial redirect to the microsite’s homepage, which may impact user experience slightly.

For embedding the microsite within an iframe on your website, we recommend using the cookie method. Setting the cookie as “HttpOnly” prevents the session token from being accessible to client-side code, reducing potential security risks. Additionally, the cookie method enables direct loading of any page within the microsite in an authenticated state, without requiring the initial redirect needed by the query parameter approach.

Passing Session via Query Parameter

To pass the session token directly in the URL, append it as a query parameter. For example:

https://MICROSITEURL.COM/api/auth?session=abc123

This configuration automatically redirects users to the microsite homepage if the session token is valid. To redirect to a different page, add a redirect_path parameter:

https://MICROSITEURL.COM/api/auth?session=abc123&redirect_path=/activity

Passing Session via Cookie

To configure session authentication using cookies, create a cookie with the following configuration and add it to the browser’s ambient environment.

The cookie domain should be set to the base domain shared between the microsite and the parent website, for example, example.com if the microsite is at microsite.example.com and the main site is at www.example.com. This setup ensures that cookies are accessible across both sites.

Name: session Domain: rootdomain.com Path: / HttpOnly: true Secure: true SameSite: None

An additional cookie may be set to support older browsers, configured as follows.

Name: session_legacy Domain: rootdomain.com Path: / HttpOnly: true Secure: true

---

Interactive authentication

With interactive authentication, the microsite handles sign-up and log-in by redirecting users through an OAuth2 flow against your identity server.

You configure the OAuth2 settings, and end-users authenticate directly with your system. Once complete, the microsite establishes a session for the user.

Interactive authentication configuration for the Loyalty Microsite

---

FAQs

Can users switch between embedded and interactive authentication?

No, each microsite instance must be configured to use either embedded or interactive authentication exclusively. Switching between the two requires a reconfiguration of the authentication setup.

How secure is embedded authentication?

Embedded authentication can be highly secure when implemented with server-side session token generation and HttpOnly cookies. Avoid exposing sensitive identifiers or tokens client-side to minimise potential security risks.

What happens if user details change on our platform?

If a user’s details are updated on your platform, you can send an updated session token request to the microsite with the new profile data, or use the Update user profile API endpoint. This process automatically updates the user’s profile in the Loyalty Engine.

What if a user is logged out of our main website but still has an active microsite session?

In embedded authentication setups, logging out from your main website doesn’t automatically log the user out of the microsite. We recommend manually invalidating the session token or refreshing the iFrame if synchronised logout is needed.

Is it possible to add custom profile fields to the session token?

Yes, custom profile fields can be included in the session token request using the profile object. These custom fields will be added to the User data, attributes & flags if they’re not core fields.

What's the default login session length on a microsite using WLL Auth Service in interactive auth mode?

If using the WLL authentication service (Auth0), user's remain logged in for 24 hours by default, after which point they will need to login again. This can be extended to up-to 30 days on request by contacting WLL Support.