Launch OIDC SSO with Mosaic hosted UI

When you integrate OIDC-based SSO using Mosaic's hosted UI, your clients need to start an OIDC authentication flow and exchange the code for tokens once the flow is completed. This page provides insights into the interaction between your system and Mosaic during an SSO flow.

Before you start

Before you start the integration, you need to have the SSO Service and SSO journeys configured.

How it works

Mosaic supports the OIDC authorization code flow for user authentication. Integrating SSO service using Mosaic hosted SSO login page involves initiating an authorization process to Mosaic's OIDC endpoint from the login page UI. This triggers the SSO journey. When the journey ends, Mosaic sends a response back to the login page app containing an authorization code, that your client exchanges for tokens, marking the user as logged in. Mosaic APIs are shown in pink along with the relevant implementation steps.

Step 1: Create a redirect URI

Create the redirect endpoint for the relying party that will receive an authorization code when the SSO authentication is completed. This code will be exchanged for user tokens, as described in Step 3. The redirect URI should accept code as a query parameter. For example, if https://domain.com/verify is your redirect URI, Mosaic will redirect to https://domain.com/verify?code=123abc when the centralized login flow is complete.

Step 2: Request centralized login

When a user requests to login, send a centralized login request like the one below (Step 1). In this OIDC authorization call, pass your client ID, and the redirect URI.

Sending the centralized login request corresponds to triggering the SSO login journey in Mosaic (Step 2). Once the SSO login is completed, an authorization code is returned by Mosaic to the requested redirect URI in the code parameter. This code will be exchanged for a token in the next step.

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 client settings in the SSO Service
url.searchParams.append("redirect_uri", YOUR_REDIRECT_URI); // Redirect URI set in the client settings in the SSO Service
window.location = url.toString();

Step 3: Get user tokens

To obtain an ID and access token, your server can send a request like the one below to the OIDC token endpoint (Step 3). Replace placeholders with the code you received in Step 2, your redirect URI, and your client credentials that can be found in your application settings from the Mosaic Admin Portal.

curl --location --request POST 'http://api.transmitsecurity.io/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=CODE' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=REDIRECT_URI'

Step 4: Log out user

To log out, the browser sends a POST request to the IDO’s /ido/api/v2/auth/sso-logout endpoint. The server will infer the SSO session(s) from the cookie, delete the associated session(s), and return a response that instructs the browser to delete the cookie(s) as well.

The SSO model allows multiple SSO sessions per browser, each correlating with a Clients-Group.

By default, the logout endpoint logs out all existing SSO sessions. To log out of a specific Clients-Group, include the group’s ID as the value of the clientsGroupId query parameter.