Follow the steps below to configure this scenario. The linked guides provide additional field descriptions and implementation details.
Real-life example: Acme Airlines has a booking website and a mobile app. A traveler who creates an account on the website can sign in to the mobile app with the same email and passkey, and the same authentication methods apply on both. Signing in on the website doesn't sign the traveler in to the mobile app.
Use case: a web app and a mobile app for the same users. Users use the same account and credentials on web and mobile. Both apps apply the same authentication policies. The mobile app doesn't share a browser session with the web app.
Resulting structure: one Mosaic application with two clients, one for the web app and one for the mobile app, and shared Mosaic application-level authentication settings. The two clients don't share a browser session.
See Choose a setup for your use case to compare all setups.
Choose the login model for each integration:
- Web app: journey-orchestrated login through an OIDC or SAML redirect, or backend-based login through Mosaic APIs or SDKs.
- Mobile app: journey-orchestrated login through a browser redirect (OIDC, Native app), or backend-based in-app login.
See Choose your login experience. Have each app's redirect URI (OIDC) or ACS URL and Entity ID (SAML) ready.
In the Admin Portal, go to Applications and create one Mosaic application for both apps. See Create Mosaic applications.
All clients in the Mosaic application share its user pool, credentials, and authentication policies. A user who signs up through the web app can sign in to the mobile app with the same account. See Plan your integration structure.
Configure the shared authentication methods once, in the Mosaic application's Authentication methods tab. See Customize login methods.
Skip this step if both clients use backend-based login. If both the web client and the mobile client are journey-orchestrated, create a separate SSO client group for each, so that the mobile app doesn't share a browser session with the web app.
Create the SSO client groups. In Applications > Application > Clients > SSO client groups, select + Add SSO client group for each journey-orchestrated client, and configure:
- SSO client group name: a name that identifies the group.
- Login screens: Hosted by Transmit Security for Mosaic-hosted pages, or Self managed (Custom UI) for a page you host.
- Login page URL: for self-managed screens, the address of the page you host. For hosted screens, Mosaic generates the URL; to show users a URL on your own domain, enter a custom login page URL. See Configure custom domains.
- Session timeout: how long the group's session stays valid. Default: 14 days, up to 1 year.
Save the group. See Configure SSO.
Create the SSO journey. In B2C or B2B Identity > Journeys, select Add blank journey and choose SSO-Journey. Build the login flow with the authentication methods configured in Step 1, then save the journey. You can also reuse an existing SSO journey. The Journeys section of Configure SSO explains where SSO journeys are created and how clients select them.
For a step-by-step example using Mosaic-hosted screens and email OTP, follow Create an SSO journey with the Mosaic-hosted experience. Adapt the journey by adding or replacing steps to match your authentication methods and login requirements.
In Applications > Application > Clients, select + Add client and choose User authentication client. Add two clients, one for the web app and one for the mobile app. For each client, complete the wizard in the tab that matches its type.
- General: enter the client name and description.
- Authentication flow: leave Does your login use OIDC or SAML authentication? enabled, select OIDC and Client type Web app, and enter the web app's Redirect URIs.
- Login Experience: select Journey-orchestrated, the client's own SSO client group, and the SSO journey from Step 2. For Mosaic-hosted screens, select a Style or use the default Mosaic style. See Manage styling for the Mosaic-hosted SSO experience.
- Advanced settings: choose the client authentication method and review token lifetimes. See OIDC advanced settings.
- Client roles: select the roles the client needs to call Mosaic APIs. If you don't select a role, the client implicitly receives the App Admin role. See Manage client roles.
Save the client. Mosaic generates the client ID and the credentials for the selected authentication method; they're available from the client details page. For all fields, see Configure an OIDC client.
If both clients are journey-orchestrated, select a different SSO client group for each, so that the mobile app doesn't share a browser session with the web app.
Integrate each app with its own client, using the tab that matches its type.
Send an authorization request with the client ID and redirect URI, exchange the returned code for user tokens from your backend, and validate the tokens before creating the app's local session. See Launch OIDC SSO with the Mosaic-hosted experience and Validate tokens.
If an SSO client group uses Self managed (Custom UI), build the login page with the Mosaic Platform SDK, which runs the SSO journey, and host it at the group's Login page URL. See Build your SSO page.
Implement session renewal and logout for each integration. Follow SSO session logout for browser SSO and Manage backend sessions for backend-based login.
To test login, use a user who belongs to this Mosaic application. Create one from Users > + Add Users, enter an email address, and select this Mosaic application. See Manage users. A login method based on email OTP can sign this user in; for passwords or passkeys, the user must register the credential first.
- A user created through one client can sign in through the other client with the same credentials.
- Changes to the Mosaic application's authentication methods apply to all clients.
- Signing in on the web app doesn't sign the user in to the mobile app, and the reverse.