{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Guides","product":"Identity Management","type":"markdown"},"seo":{"title":"Configure SAML clients","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"configure-saml-clients","__idx":0},"children":["Configure SAML clients"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this guide to create a SAML user authentication client for a customer-facing application acting as a service provider."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before you start"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/create_new_application"},"children":["Create a Mosaic application"]}," for the client."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtain the service provider's ACS URL and Entity ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/login_experience"},"children":["Choose your login experience"]},". For journey-orchestrated login, prepare an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_journeys"},"children":["SSO journey"]}," and an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_config_service#client-groups"},"children":["SSO client group"]},", or create the group inline."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Applications"]}," > your app > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clients"]},", click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Add client"]}," and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["User authentication client"]},". Leave OIDC/SAML authentication enabled and choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML"]}," in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication flow"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1---general","__idx":2},"children":["Step 1 - General"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client name to display when needed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Short description of your client."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2---authentication-flow","__idx":3},"children":["Step 2 - Authentication flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML"]}," as the protocol, this step shows the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML settings"]}," section."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Does your login use OIDC or SAML authentication?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enabled by default. Leave it enabled for protocol-based authentication, then select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OIDC"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML"]},". Disable it for backend-based authentication through Mosaic APIs or SDKs; the saved client is then an OIDC client (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/configure_oidc_client#backend-based-authentication"},"children":["Backend-based authentication"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Protocol"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Setting to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML"]}," defines that this client is SAML-based."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Service provider (SP) ACS URL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Service provider (SP) Entity ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3---login-experience","__idx":4},"children":["Step 3 - Login Experience"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Journey-orchestrated"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Application-controlled"]},". For the journey-orchestrated path, select the required ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_config_service#client-groups"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SSO client group"]}]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Journey"]},". When the group uses Mosaic-hosted screens, select a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Style"]}," or use the default Mosaic style. The journey and style are configured per client. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/login_experience"},"children":["Choose your login experience"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4---additional-information","__idx":5},"children":["Step 4 - Additional information"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NameID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Choose the user identifier sent in the SAML assertion. The default value is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Email"]},". Options include ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Email"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Secondary Email"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Username"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Phone Number"]},", and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["External User ID"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sign SAML assertion"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If enabled, in addition to the signing of the entire SAML response Mosaic signs the SAML assertion with the generated X.509 certificate."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Allow the ACS URL to be optional in SAML requests"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If enabled, the SAML AuthnRequest can omit the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AssertionConsumerServiceURL"]},", and Mosaic uses the ACS URL configured on the client instead. Checking this option may reduce security by disabling ACS URL validation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Same Site > LAX"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Same Site > None"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allows sharing Mosaic session cookies in cross-site or iframe scenarios. Requires HTTPS (Secure cookies) and an HTTPS ACS URL."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"after-saving","__idx":6},"children":["After saving"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete the wizard and save the client. SAML clients do not have a Client roles step."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upon SAML client creation, Mosaic will autogenerate a unique SAML SSO URL, Transmit Entity ID, X.509 Certificate and IDP metadata URL."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transmit Entity ID"]},": ID that uniquely identifies the Mosaic IDP in the SAML exchange, ensuring that SAML requests are routed to the Mosaic."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["X.509 Certificate"]},": The certificate used to sign SAML assertions, securing communication between the service provider and the identity provider."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["IDP metadata URL"]},": The Mosaic endpoint that contains structured metadata about the IDP's configuration."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the generated values to configure the service provider. For journey-orchestrated login with Mosaic-hosted screens, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_quickstart_hosted_ui_saml"},"children":["Launch SAML SSO"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":7},"children":["Related guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/manage_clients"},"children":["Manage clients"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/login_experience"},"children":["Choose your login experience"]}]}]}]},"headings":[{"value":"Configure SAML clients","id":"configure-saml-clients","depth":1},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1 - General","id":"step-1---general","depth":2},{"value":"Step 2 - Authentication flow","id":"step-2---authentication-flow","depth":2},{"value":"Step 3 - Login Experience","id":"step-3---login-experience","depth":2},{"value":"Step 4 - Additional information","id":"step-4---additional-information","depth":2},{"value":"After saving","id":"after-saving","depth":2},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"title":"SAML clients","markdown":{"toc":{"depth":2}},"seo":{"title":"Configure SAML clients"}},"lastModified":"2026-10-15T11:23:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/user/configure_saml_client","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}