SSO Integration guidelines

General guide to SSO Integration: prerequisites, access tokens, iframes and webviews

How identity integration works

Identity integration is dictated by context, the configuration of your systems and choices made in the process. Each instance is treated as a project with a solution specification created by our solutions architects with you.

This advice is therefore designed to give you an overview of concepts and methods involved in general terms.

Terms

• Our systems:

  • FanKit: Monterosa Experiences are web apps provided by Monterosa and are built on our FanKit JavaScript/React framework.

  • Identify: The Monterosa identity provider, called Identify, is an interface between your identity system or SSO and our applications.

• Your systems:

  • Identity Provider: We refer to your internal identity solution as Identity Provider

  • Client Application: When embedded into your site or native app, we refer to the parent as a Client Application.

Prerequisites

There are some prerequisites for all integrations.

Your application takes responsibility for sign-in flow and managing the state of the user's session.

You must be in control of the 'parent' website or native app and able to make minor changes to it.

Your identity provider must also provide a way for third party systems to validate sessions. Any of the following three methods are supported:

1. A public API endpoint

2. A JWK file URL (if the access token is a standard JWT and the SSO Provider is based on standards like OpenID or oAuth2.0)

3. An access token cryptographic public key that can be stored by our Identify backend to decode it

Note that methods 2 and 3 do not require any exposed endpoint from the SSO Provider and are the preferred way to avoid a high volume of calls.

Providing access tokens

When a user is logged into your site or app, your Client Application must provide the Monterosa App an access token via iFrame or WebView using one of three methods:

1. Query String

2. Cookie

3. Local Storage

iframe & WebView bi-directional communication

Monterosa FanKit is able to communicate back to your Client Application with messages including:

1. Login button CTA

2. Page sizes changing

3. User not valid

4. Other custom CTAs - for instance the opening of an external link

Bi-directional communication can be established using:

1. WebView post messages

2. Deep links related to native apps

Your Client Application developer must put in place a method to capture the post messages or deep links that FanKit generates, and act upon them.