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. |
| Encrypt SAML assertion | If enabled, Mosaic encrypts the SAML assertion with the service provider's public encryption certificate, so only the service provider can read it. The SAML response then carries an EncryptedAssertion. If Sign SAML assertion is also enabled, Mosaic signs the assertion before encrypting it. Configure the encryption in Assertion encryption settings:
|
| 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. |
Each SAML client has one encryption certificate. Under the certificate, the Admin Portal shows when it was uploaded and when it expires. To rotate it, click Replace certificate and paste the new certificate, which replaces the previous one. Mosaic then encrypts assertions only with the new certificate, so make sure the service provider can decrypt with the matching private key before you replace it. If you disable Encrypt SAML assertion, Mosaic keeps the certificate and uses it again when you re-enable encryption.
Mosaic doesn't check the certificate's expiration: it keeps encrypting assertions with an expired certificate and never sends them unencrypted. When the certificate expires, the Admin Portal shows an Expired tag next to its dates.
Starting 45 days before the encryption certificate expires, the Applications page and the client table in Applications > your application > Clients display a warning that prompts you to upload a new certificate in the client's settings. After expiration, they display an urgent alert. No alerts are displayed while Encrypt SAML assertion is disabled.
Signing and encryption protect the SAML assertion in different ways and use different certificates:
- Signing proves that the SAML assertion comes from Mosaic and wasn't modified. Mosaic signs with its own private key, and the service provider verifies the signature with the Mosaic X.509 certificate. A signed assertion remains readable. To rotate the signing certificate, see Rotate SAML signing certificates.
- Encryption makes the assertion readable only by the service provider. Mosaic encrypts with the service provider's public encryption certificate, and the service provider decrypts with its own private key.
When both are enabled, Mosaic signs the assertion, encrypts it, and then signs the entire SAML response. The service provider decrypts the assertion with its private key and verifies the signatures with the Mosaic certificate.
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.