Using SSO with Mosaic hosted UI

Ready to implement SSO yourself? Through a practical example, this tutorial walks you through the main steps for implementing SSO using Mosaic hosted SSO UI (see Launch SSO with Mosaic hosted UI quickstart).

This tutorial demonstrates how to set up an SSO service and configure a journey that implements SSO with an OTP authentication method via email or SMS, allowing users to authenticate once and seamlessly access a relying party with the same credentials. After this tutorial, you'll be familiar with the main stages of SSO configuration and ready to strategize your own SSO journeys.

  1. Set up Mosaic SSO Service in the Admin Portal.
  2. Set up the SSO authentication policy, that is, the authentication methods supported by SSO.
  3. Build your SSO journey by leveraging Mosaic orchestration capabilities.
  4. Test SSO authentication

Prerequisites

In our example, we’ll build a basic login journey for users who are already registered in our application. Ensure you have a registered user before attempting to run this journey.

To quickly create a user, in the Orchestration section, use the Create User template to set up a new journey. Utilize the Test Journey feature to add a user, who will then appear under Identity Management in the Users section.

Make sure this user is created and available before proceeding with the steps in this tutorial.

Step 1: Set up Mosaic SSO Service

➊   Set up the SSO Page URL

In this example, when the user initiates SSO authentication at runtime, they'll be redirected to a Mosaic-hosted SSO page. In SSO Service > Service Definition, set the URL as https://sso-app.transmitsecurity.io to use the Mosaic-hosted UI.

➋   Configure client groups

A client group allows you to group multiple OIDC clients (relying parties) into an SSO group. Logging into one client enables SSO login to other clients within the group. In this example, we define a single group and a single client.

In SSO Service > Authentication Policy > Client Groups, configure the following:

  • Group Name, Description: Enter a name and description for your client group.
  • Journey: Specify the name of the SSO journey to apply to the client group.
Note

Ensure the journey name matches this data when creating the journey.

For the purposes of this example, leave other settings as default.

➌   Configure client

In this example, we set up a single client, or relying party, to which your user can authenticate using the same email registered to your main app. From the client group settings, add a client and configure the following:

  • Redirect URI: Specify the URI that redirects to the relying party after authentication. For the purpose of this example, we use http://localhost:3333/back-from-oidc but it can vary based on your setup.
  • Client Name, Description: Enter a name and description for your client.

For the purposes of this example, leave other settings as default.

Step 2: Set up the SSO authentication policy

In SSO Service > Authentication Policy, set up the email OTP code length. To do so, in One-time Passcodes, configure the length of the one-time code to be six digits.

For the purposes of this example, leave other settings as default.

Step 3: Build your SSO journey

Mosaic SSO journeys stand apart from regular journeys by combining the seamless authentication experience of OIDC with the flexibility of orchestration journeys, eliminating the need for client-side development. This allows you to focus on creating a login flow tailored to your needs, with SSO capabilities built into the SSO journey type.

➊   Add an SSO journey

Start by creating a blank SSO journey. You can do it in the Admin Portal, by proceeding to Orchestration > Identity journeys. Select the SSO Journey type.

Name your journey with the same name used in the client group setup.

➋   Design your login journey

In our example, we’ll build a basic login journey for users who are already registered in our application. The journey involves:

  • Login form step: The login form collects the user’s email address. The output variable is loginData1.
  • Email OTP authentication step: This step sends an OTP to the provided email (loginData1.email), validates it against the sent code, and upon successful verification, authenticates the user and completes the login process.

At runtime, users seeking to authenticate to a relying party's resources will use the same email they use to authenticate to your main app.

Step 4: Test SSO authentication

To test the login flow paste the following URL into your browser, to run the following call to the SSO endpoint:

Copy
Copied
let url = new URL("https://api.transmitsecurity.io/cis/oidc/auth?&response_type=code&prompt=login&scope=openid%20email");
url.searchParams.append("client_id", YOUR_CLIENT_ID); // Client ID auto generated in step 1.3
url.searchParams.append("redirect_uri", YOUR_REDIRECT_URI); // Redirect URI set Client ID in step 1.3
window.location = url.toString();

The Mosaic hosted SSO login UI is displayed, and the user is prompted to enter their email, and then to authenticate with an email OTP. Notice how, upon successful authentication, the browser is redirected to the indicated redirect URI with a code.

To exchange the code received from Mosaic for an ID and access token, your server should send a POST request like the one below to the Mosaic /oidc/token endpoint. This request returns user tokens that should grant user access to your resources. Before granting access, verify the tokens' validity. To know more, see Validate tokens.