{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab"]},"redocly_category":"Guides","product":"Identity Management","type":"markdown"},"seo":{"title":"Enable SSO between web apps","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":"enable-sso-between-web-apps","__idx":0},"children":["Enable SSO between web apps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow the steps below to configure this scenario. The linked guides provide additional field descriptions and implementation details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Real-life example:"]}," Acme Bank offers online banking and a mortgage portal. A customer who signs in to online banking can open the mortgage portal without signing in again."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use case:"]}," two or more web apps for the same users. Users sign in to one web app and can access the other without signing in again while the shared session remains valid."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resulting structure:"]}," one Mosaic application, one user authentication client per web app configured for OIDC or SAML, and one shared SSO client group. Each client uses journey-orchestrated login."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/use_case_sso_business_units.dddb6fd069f43efa4bde7f0caf5edf6a2eab5c2eb67c7822bc860baf0e39dfed.bdd3aebe.svg","alt":"Example: one Acme Bank Mosaic application with one shared SSO client group. The group contains the online banking client and the mortgage portal client, each configured for OIDC or SAML, both with journey-orchestrated login."},"children":[]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Not this use case?"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/use_cases"},"children":["Choose a setup for your use case"]}," to compare all setups."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Have the following ready for each web app:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For OIDC: the redirect URI the web app receives the authorization code on."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For SAML: the service provider (SP) ACS URL and Entity ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The login methods and screen-hosting option to use across the group."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-the-mosaic-application","__idx":2},"children":["Step 1: Create the Mosaic application"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the Admin Portal, go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Applications"]}," and create one Mosaic application for all the web apps. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/create_new_application"},"children":["Create Mosaic applications"]},". Clients in the same Mosaic application share the user pool, so a user has one account across the web apps."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure the authentication methods your users will use in the Mosaic application’s ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication methods"]}," tab. For the settings and prerequisites of each method, follow ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/auth_methods_customize"},"children":["Customize login methods"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"id":"step-2-create-the-sso-client-group"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"id":"step-2-prepare-the-shared-group-and-login-journeys"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-prepare-the-sso-client-group-and-login-journeys","__idx":3},"children":["Step 2: Prepare the SSO client group and login journeys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Mosaic application gives users one account across the web apps. Placing all the web apps in the same SSO client group is what lets them share the login session: create one group shared by all the web apps."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create the SSO client group."]}," In ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Applications"]}," > Application > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clients"]}," > SSO client groups, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Add SSO client group"]},", and configure:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SSO client group name"]},": a name that identifies the group."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Login screens"]},": ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hosted by Transmit Security"]}," for Mosaic-hosted pages, or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Self managed (Custom UI)"]}," for a page you host."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/custom_domains"},"children":["Configure custom domains"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Session timeout"]},": how long the group's session stays valid. Default: 14 days, up to 1 year."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the group. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_config_service#client-groups"},"children":["Configure SSO"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create the SSO journey."]}," In ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["B2C"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["B2B Identity"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Journeys"]},", select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add blank journey"]}," and choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 web apps can use the same journey or different ones. The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Journeys"]}," section of ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_config_service#journeys"},"children":["Configure SSO"]}," explains where SSO journeys are created and how clients select them."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add an SSO session validity step to the journey."]}," Route users with a valid group session past credential collection, and users without one through the authentication steps. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/orchestration/journeys/has_valid_sso_session"},"children":["SSO session validity"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_journeys#sso-journey-logic"},"children":["SSO journeys"]},"."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a step-by-step example using Mosaic-hosted screens and email OTP, follow ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/orchestration/sso/sso_tutorial"},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-add-one-client-per-web-app","__idx":4},"children":["Step 3: Add one client per web app"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Applications"]}," > Application > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clients"]},", select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Add client"]},", choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["User authentication client"]},", and complete the wizard for each web app in the tab that matches its protocol."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each client uses the protocol its web app supports. Clients in the same SSO client group can use different protocols, for example OIDC for one web app and SAML for another."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"OIDC web app","disable":false},"children":[{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["General"]},": enter the client name and description."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication flow"]},": leave ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Does your login use OIDC or SAML authentication?"]}," enabled, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OIDC"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client type"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Web app"]},", and enter the web app's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Redirect URIs"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Login Experience"]},": select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Journey-orchestrated"]},", the shared group from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-2-prepare-the-sso-client-group-and-login-journeys"},"children":["Step 2"]},", and the SSO journey for this web app. For Mosaic-hosted screens, select a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Style"]}," or use the default Mosaic style. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/platform/hosted_ui_styles"},"children":["Manage styling for the Mosaic-hosted SSO experience"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Advanced settings"]},": choose the client authentication method and review token lifetimes and security settings. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/configure_oidc_client#step-4---advanced-settings"},"children":["OIDC advanced settings"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client roles"]},": select the roles the client needs to call Mosaic APIs. If you don't select a role, the client implicitly receives the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["App Admin"]}," role. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/manage_client_roles"},"children":["Manage client roles"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the client. Mosaic generates the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["client ID"]}," and the credentials for the selected authentication method; they're available from the client details page. For all fields, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/configure_oidc_client"},"children":["Configure an OIDC client"]},"."]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"SAML web app","disable":false},"children":[{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["General"]},": enter the client name and description."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication flow"]},": leave ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Does your login use OIDC or SAML authentication?"]}," enabled, select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML"]},", and enter the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Service provider (SP) ACS URL"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Service provider (SP) Entity ID"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Login Experience"]},": select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Journey-orchestrated"]},", the shared group from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#step-2-prepare-the-sso-client-group-and-login-journeys"},"children":["Step 2"]},", and the SSO journey for this web app. For Mosaic-hosted screens, select a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Style"]}," or use the default Mosaic style. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/platform/hosted_ui_styles"},"children":["Manage styling for the Mosaic-hosted SSO experience"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Additional information"]},": select the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NameID"]}," and review assertion signing, ACS validation, and the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Same Site"]}," cookie policy. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/configure_saml_client#step-4---additional-information"},"children":["SAML additional information"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["SAML clients have no Client roles step."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the client. Mosaic generates the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML SSO URL"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transmit Entity ID"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["X.509 Certificate"]},", and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["IDP metadata URL"]}," to configure in the app, which acts as the service provider. For all fields, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/configure_saml_client"},"children":["Configure a SAML client"]},"."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the generated values to integrate the corresponding web app."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-integrate-the-web-apps","__idx":5},"children":["Step 4: Integrate the web apps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integrate each web app with its own client, using the tab that matches its protocol."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"OIDC web app","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_quickstart_hosted_ui_oidc"},"children":["Launch OIDC SSO with the Mosaic-hosted experience"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/validate_tokens"},"children":["Validate tokens"]},"."]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"SAML web app","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redirect users to the client's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SAML SSO URL"]},", then verify the SAML response and assertion at the ACS URL before creating the app's local session. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_quickstart_hosted_ui_saml"},"children":["Launch SAML SSO with the Mosaic-hosted experience"]},"."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the SSO client group uses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Login page URL"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_quickstart_selfhosted_ui"},"children":["Build your SSO page"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To allow session reuse, do not force a fresh login on every authorization request. To log users out, end their SSO session with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_logout_api"},"children":["SSO session logout"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"check-the-result","__idx":6},"children":["Check the result"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To test login, use a user who belongs to this Mosaic application. Create one from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Users"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Add Users"]},", enter an email address, and select this Mosaic application. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/manage_users#create-edit-or-delete-users"},"children":["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."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sign in to the first web app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the second web app in the same browser. The journey detects the active session and the user isn't asked for credentials again."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After the group's session timeout, or after logout, the user must sign in again. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/user/sso_orchestration/sso_logout_api"},"children":["SSO session logout"]},"."]}]}]},"headings":[{"value":"Enable SSO between web apps","id":"enable-sso-between-web-apps","depth":1},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1: Create the Mosaic application","id":"step-1-create-the-mosaic-application","depth":2},{"value":"Step 2: Prepare the SSO client group and login journeys","id":"step-2-prepare-the-sso-client-group-and-login-journeys","depth":2},{"value":"Step 3: Add one client per web app","id":"step-3-add-one-client-per-web-app","depth":2},{"value":"Step 4: Integrate the web apps","id":"step-4-integrate-the-web-apps","depth":2},{"value":"Check the result","id":"check-the-result","depth":2}],"frontmatter":{"title":"SSO between web apps","seo":{"title":"Enable SSO between web apps"}},"lastModified":"2026-10-15T11:23:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/user/use_case_sso_business_units","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}