This page explains how Mosaic structures your integration—tenants, applications, and clients—and how to map your business structure to the right setup. Read it before creating your first application.
Your tenant is the top-level administrative and operational boundary—it represents the full identity universe of your company in Mosaic. A tenant can include many Mosaic applications, and Mosaic maintains one unified record per real user at the tenant level. This provides centralized user management, even when users participate in multiple Mosaic applications.
Depending on assigned permissions, users can be viewed and managed at the tenant scope, within a specific Mosaic application's scope, or both. Centralized user management doesn't imply shared credentials or shared sessions—those are controlled at the Mosaic application and SSO client group levels described below.
For tenant-wide administrative operations, such as managing users and settings across Mosaic applications, use management apps.
A Mosaic application is three things at once: an isolated user pool, the container for the clients that share it, and a set of policies applied to those clients and their users, such as authentication methods and token signing keys.
Mosaic maintains one unified person record at the tenant level, but each Mosaic application has its own user accounts. A user must register separately in each Mosaic application whose clients they sign in to, and their credentials are scoped to it. The same real person can therefore have multiple Mosaic application accounts linked to one tenant-level person record.
- As a container, a Mosaic application holds your clients.
- As a set of policies, it defines the configuration they share, including branding, authentication methods, token signing keys, and device limits.
Clients under the same Mosaic application operate on the same user pool and are governed by the same authentication policies. A user who signs up through one client can therefore use another client in the same Mosaic application without registering a separate account.
Group clients into the same Mosaic application when they should share the same user pool, credentials, authentication methods, and policies. When they require isolated identities or credentials, place them in separate Mosaic applications.
The word application means two different things here, and they sit at different levels of the model. To keep them apart, these guides always name them in full: Mosaic application and customer-facing application.
| Mosaic application | Your customer-facing application |
|---|---|
| The isolated user pool and configuration container you create in the Admin Portal. It holds user accounts, clients, and their common configuration. Your users never interact with it directly. | Your website, mobile app, or backend service—what your users actually use. It connects to Mosaic as a client, not as a Mosaic application. |
To create and configure Mosaic applications, see Create Mosaic applications and Manage Mosaic applications.
A client is the channel and technical entity through which a customer-facing application communicates with Mosaic APIs. Each customer-facing application or service—your website, your mobile app, a backend service—connects through its own client, which carries its own settings. Each client belongs to exactly one Mosaic application.
As a best practice, use one client per integration—for example, a web client for your browser app and separate native clients for your Android and iOS apps.
Client creation starts by selecting the applicable client type:
- User authentication client: for end-user authentication.
- Service client: for Fraud Prevention, Identity Verification, and machine-to-machine (M2M) use cases.
For a user authentication client, step 2 asks whether the login uses OIDC or SAML. Turn this option off for backend-based authentication through Mosaic APIs or SDKs. See Choose your login experience. For the complete creation flow and settings, see Manage clients.
An SSO client group is the browser-session boundary for journey-orchestrated clients inside a Mosaic application. It defines where login screens are hosted, the login page URL, and the session timeout, and answers a central question—once a user has logged in to one client, which other clients may treat them as already logged in?
- Every journey-orchestrated client must select an SSO client group.
- Clients in the same SSO client group may share browser sessions.
- Clients in different SSO client groups don't share sessions.
Select what runs the login flow in the client's Login Experience. For journey-orchestrated login, configure who hosts the screens on the SSO client group, and select the journey and style per client. See Choose your login experience.
- Identity isolation is enforced per Mosaic application: each one has its own user accounts and credentials.
- Login experience determines who controls the flow and who hosts the screens.
- Session sharing is enforced at the SSO client group level. Journey-orchestrated clients in the same group may share a browser session.
- Client setup determines how authentication happens, not who the user is.
- Centralized user management doesn't imply shared credentials or shared sessions.
- A real person has one unified record in the tenant and can have separate accounts and credentials in multiple Mosaic applications.