Use this guide to create a SAML user authentication client for a customer-facing application acting as a service provider.
- Create a Mosaic application for the client.
- Obtain the service provider's ACS URL and Entity ID.
- Choose your login experience. For journey-orchestrated login, prepare an SSO journey and an SSO client group, or create the group inline.
In Applications > your app > Clients, click + Add client and select User authentication client. Leave OIDC/SAML authentication enabled and choose SAML in Authentication flow.
| Field | Description |
|---|---|
| Client name | Client name to display when needed. |
| Client description | Short description of your client. |
When you select SAML as the protocol, this step shows the SAML settings section.
| Field | Description |
|---|---|
| Does your login use OIDC or SAML authentication? | Enabled by default. Leave it enabled for protocol-based authentication, then select OIDC or SAML. Disable it for backend-based authentication through Mosaic APIs or SDKs; the saved client is then an OIDC client (see Backend-based authentication). |
| Protocol | Setting to SAML defines that this client is SAML-based. |
| Service provider (SP) ACS URL | The endpoint where SAML responses containing authentication assertions are sent after the user successfully logs in. This URL must be configured accurately to ensure that the authentication data is received and processed by the intended service provider. |
| Service provider (SP) Entity ID | ID that uniquely identifies the service provider within the SAML framework. This is crucial for ensuring that the SAML responses are directed to the correct client, maintaining the integrity and security of the authentication process. |
Choose Journey-orchestrated or Application-controlled. For the journey-orchestrated path, select the required SSO client group and Journey. When the group uses Mosaic-hosted screens, select a Style or use the default Mosaic style. The journey and style are configured per client. See Choose your login experience.
| Field | Description |
|---|---|
| NameID | Choose the user identifier sent in the SAML assertion. The default value is Email. Options include Email, Secondary Email, Username, Phone Number, and External User ID. |
| Sign SAML assertion | If enabled, in addition to the signing of the entire SAML response Mosaic signs the SAML assertion with the generated X.509 certificate. |
| Allow the ACS URL to be optional in SAML requests | If enabled, the SAML AuthnRequest can omit the AssertionConsumerServiceURL, and Mosaic uses the ACS URL configured on the client instead. Checking this option may reduce security by disabling ACS URL validation. |
| Same Site > LAX | Allows Mosaic session cookies to be sent during standard navigation flows while blocking most cross-site requests, such as iframes and POSTs. This works for most apps and provides strong CSRF protection with minimal impact on typical sign-in experiences. |
| Same Site > None | Allows sharing Mosaic session cookies in cross-site or iframe scenarios. Requires HTTPS (Secure cookies) and an HTTPS ACS URL. |
Complete the wizard and save the client. SAML clients do not have a Client roles step.
Upon SAML client creation, Mosaic will autogenerate a unique SAML SSO URL, Transmit Entity ID, X.509 Certificate and IDP metadata URL.
- SAML SSO URL: The URL acts as the gateway for routing login requests through the correct SSO mechanism. This URL must be set within the relying party (RP).
- Transmit Entity ID: ID that uniquely identifies the Mosaic IDP in the SAML exchange, ensuring that SAML requests are routed to the Mosaic.
- X.509 Certificate: The certificate used to sign SAML assertions, securing communication between the service provider and the identity provider.
- IDP metadata URL: The Mosaic endpoint that contains structured metadata about the IDP's configuration.
Use the generated values to configure the service provider. For journey-orchestrated login with Mosaic-hosted screens, see Launch SAML SSO.