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:

Sign in your user in order to obtain the JWT token
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:

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

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

These docs have been created referencing our core App, FanKit. Some settings may differ if you are using your own custom App. For any custom App questions please use your dedicated customer hub.

import {
  onReady,
} from "@monterosa/sdk-launcher-kit";
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',
});

// experience was configured previously
onReady(experience, async () => {
  await setCredentials(identify, { token: '...' });
});

These docs have been created referencing our core App, FanKit. Some settings may differ if you are using your own custom App. For any custom App questions please use your dedicated customer hub.

import {
  onReady,
} from "@monterosa-sdk/launcher-kit";
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',
});

// experience was configured previously
onReady(experience, async () => {
  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

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:

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

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

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

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

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.

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

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

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

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

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

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

Is there support for Open ID Connect (OIDC)

Yes, our platform supports Open ID Connect (OIDC) for seamless identity management. Connect with any OIDC-compliant provider to enable secure single sign-on, maintain consistent user identities across platforms, and leverage your existing authentication infrastructure.

Last updated 21 days ago

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

hashtagListening to credentials validation failure

hashtagIs there support for Open ID Connect (OIDC)

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

Listening to credentials validation failure

Is there support for Open ID Connect (OIDC)