Set up identity using the SDK & JWT

Identity integration using JWT and built-in identity management features

In this use-case, the Monterosa Experience is embedded into a site or app that requires the user to be signed-in.

If a non-signed-in user attempts to use the Experience, they will be prompted to sign in before continuing.

All users accessing the embedded Experience will therefore have a JWT token available to pass to the Monterosa SDK.

Note, this guide assumes the SDK is already in use in your systems, if it isn’t please follow the instructions you’ll find here, or contact Sales or your Account Manager if you need any further guidance.

The SDK offers a standardised approach to this integration, reducing the effort involved on your side to a two step process:

1. Sign in your user in order to obtain the JWT token

2. Provide to the SDK the JWT token

Make sure that the JWT includes a key id (kid) in its header so that we know which key to use from your JWKS.

The SDK allows you to set the JWT token via a call to the setCredentials method:

iOS

let identify = Identify.default
let credentials = UserCredentials(token: "...")
identify.setCredentials(credentials: credentials)

Android

val identifyKit: IdentifyKit = IdentifyKit.default() 
identifyKit.credentials = Credentials(token = "...")

// If you are embedding an Experience also set Identify in 
// ExperienceView when creating the experience:
experienceView.identify = identifyKit

JavaScript

import { getIdentify, setCredentials } from "@monterosa-sdk/identify-kit";

const identify = getIdentify({
  // Make sure to store this id and re-use it in future sessions.
  deviceId: UUID()
  // Always use email
  strategy: 'email',
});

await setCredentials(identify, { token: '...' });

You can then follow the instructions to embed the Experience into your page using the SDK as described here.

See also our SSO Integration guidelines for more general information on this integration

Access Gating: listening for login requests and triggering your login flow

Some Experiences may require login upfront and others may support login-gated content at a specific point in the user journey, for example a "Login or Register" call to action when the user tries to access restricted content.

When the user reaches that point, a request to login is sent from the Experience, via the SDK, to your parent app or site. Your code will be listening for those messages and from there, you will trigger the same login flow in your application.

In order to capture that notification and integrate your own login flow, you’ll need to implement listeners to onLoginRequestedByExperience:

iOS

let delegate = IdentifyViewController()
Identify.default.add(delegate: delegate)

class IdentifyViewController: IdentifyKitAPIDelegate {
    func didRequestLoginByExperience() {
        // Implement here
    }
}

Android

identifyKit.add(object : IdentifyKitListener {
    override fun onLoginRequestedByExperience() {
        // your code here
    }
})

JavaScript

import { getIdentify, onLoginRequestedByExperience } from "@monterosa-sdk/identify-kit";

const identify = getIdentify();
const unsub = onLoginRequestedByExperience(identify, () => {
  // Implement here
});

Listening to credentials validation failure

The onCredentialsValidationFailed() function enables you to set up an event listener that is triggered when a credential validation failure occurs. This listener is invoked regardless of who initiates the call to Identify (whether the Experience or the App) and who is subscribed to it, as well as the kind of error.

iOS

let delegate = IdentifyViewController()
Identify.default.add(delegate: delegate)

class IdentifyViewController: IdentifyKitAPIDelegate {
    func didFailCredentialsValidation(error: Error) {
        // Implement here
    }
}

Android

Android snippet

identifyKit.add(object : IdentifyKitListener {
    override fun onCredentialsValidationFailed(exception: Exception) {
        // your code here
    }
})

JavaScript

import { getIdentify, onCredentialsValidationFailed } from "@monterosa-sdk/identify-kit";

const identify = getIdentify();
const unsub = onCredentialsValidationFailed(identify, (error) => {
  console.log(error);
});