Skip to content

Create an SSO journey with the Mosaic-hosted experience

This tutorial builds a Mosaic-hosted login journey that authenticates registered users with email OTP. It covers the SSO client group, authentication settings, journey, and an OIDC client used to test the flow.

  1. Create the SSO client group.
  2. Configure email OTP.
  3. Create and build the SSO journey.
  4. Configure the OIDC client and test login.

For other login methods or SAML integration, use the same group/client model and follow the relevant method or protocol guide. See Configure SSO.

Prerequisites

  • Create a Mosaic application, or select an existing one.
  • Prepare a user registered with that application and an email address that can receive the OTP. For user creation or application association, follow Manage users.
  • Prepare the web application's OIDC redirect URI for the login test.

Step 1: Set up SSO on your application

➊   Configure the SSO client group

An SSO client group defines the login page and session policy shared by its clients. Clients can reuse the group’s session through their SSO journeys. This example uses one group and one client.

In Applications > your app > Clients tab > SSO client groups, click + Add SSO client group (or use the APIs), and configure the following:

  • SSO client group name, Description: Enter a name and description for your client group.
  • Login screens: Select Hosted by Transmit Security. Mosaic generates the URL of the login page for this group. You can also enter a custom login page URL on your own domain; for this example, use the generated one.

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

Step 2: Set up the authentication methods

In Applications > your app > Authentication methods tab, 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

The SSO journey defines the login flow shown on the Mosaic-hosted pages. The client will select this journey in Login Experience after you build it.

➊   Add an SSO journey

In B2C or B2B Identity (based on your setup) > Journeys, select Add blank journey, choose SSO-Journey, and give it a name. You can also edit an existing SSO journey. For the creation and assignment procedure, follow Create an SSO journey.

➋   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.

Save the journey. To support access without another login while the group session is valid, configure the session-reuse branch described in SSO journey logic.

Step 4: Test SSO authentication

Create a User authentication client in Applications > your app > Clients, using these settings:

  • Protocol: OIDC, with Client type set to Web app and the redirect URI prepared earlier.
  • Login Experience: Journey-orchestrated, the group from Step 1, and the journey saved in Step 3.
  • Style: a saved style or the default Mosaic style.

Review client authentication, token settings, and client roles, then save the client and obtain its client ID and configured credentials. For the wizard procedure, follow Configure OIDC clients.

From your web app, initiate an OIDC authorization request like the following, using your client ID and registered redirect URI. This example uses prompt=login to test a fresh authentication; omit forced login when testing reuse of an active SSO session.

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 from the saved client
url.searchParams.append("redirect_uri", YOUR_REDIRECT_URI); // Redirect URI registered on the client
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.

Exchange the returned code for tokens from your backend using the client's configured authentication method. Follow Get user tokens for the request, then validate the tokens before signing the user in.