Configure SSO Service

This page illustrates the SSO Service configuration, which involves designing SSO journeys, configuring OIDC or SAML clients and grouping them based on their assigned SSO journey.

SSO login page hosting & branding

The SSO authentication process begins when a user requests to log in from your client application. This triggers a redirection to a dedicated SSO page, which can be hosted either by you or by Mosaic. Set the SSO page URL in SSO Service > Service Definition > Configuration.

  • For an SSO login page hosted by you , enter the relevant URL. You will have full control over the page's appearance and customization.
  • For a Mosaic-hosted SSO login page , enter the appropriate URL based on your location:
    • US and Global : https://sso-app.transmitsecurity.io
    • EU : https://sso-app.eu.transmitsecurity.io

When you choose the Mosaic-hosted SSO login page, you can customize it through the Admin Portal to align with your brand identity. Navigate to SSO Service > Experiences Management to update the primary and background colors to match your branding. The primary color will be applied to key elements like buttons and navigation. Additionally, you can upload your application logo to display on the SSO login page. These customization options ensure a consistent and branded experience across all your authentication journeys involving SSO.

SSO service branding options

Client groups

In SSO, the organizations you want to link with SSO are configured in the Admin portal as clients. SSO is applied to groups of clients . In SSO Service > Service Definition > Client groups you create your group of clients.

Set clients with OIDC OIDC clients can be set up as either first-party (trusted applications belonging to your organization) or third-party, that are external applications that require explicit user consent for access. For more, see our Consent APIs.

The client type determines certain configurations and validations. Web App is selected for web-based applications, while Native App is chosen for applications installed on devices. This choice influences settings such as the redirect URI. For instance, a web app would need a URL redirect, whereas a native app might use a custom URI scheme like myapp://callback.

In both cases, specify the Redirect URIs to determine where users should be redirected after authentication.

Optionally, you can define a set of resources the client can access. This helps in providing SSO to specific or limited resources of an application or external services. For example, you might restrict access to user profile data and payment services only, ensuring that the client has limited and targeted access.

For more about implementing SSO with OIDC, see our Launch SSO with Transmit hosted UI quickstart.

Set clients with SAML

For SAML clients, you need to specify the Service provider (SP) ACS URL, which is 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 application.

Additionally, specify the Service Provider (SP) Entity ID, which uniquely identifies the service provider within the SAML framework. This is crucial for ensuring that the SAML responses are directed to the correct client application, maintaining the integrity and security of the authentication process.

After saving the SAML client configurations, Mosaic will autogenerate the following parameters, which are required on the Service Provider side:

  • The SAML SSO URL is created after saving the configuration and must be set within the relying party (RP). This URL acts as the gateway for routing login requests through the correct SSO mechanism.
  • The Transmit Entity ID uniquely identifies the Mosaic IDP in the SAML exchange, ensuring that SAML requests are routed to the Mosaic SSO service.
  • The X.509 Certificate is used to sign SAML assertions, securing communication between the application and the identity provider. This certificate is automatically populated after the configuration is saved.

For more about implementing SSO with SAML, see our Launch SAML SSO with hosted UI.

Session timeout

In SSO journeys, when a user requests to authenticate to an app within a client group, the first step is to verify if a user session is active (using the Has Valid SSO Session step). The session timeout defines how long a user session remains valid before re-authentication is required. This ensures the journey takes appropriate actions based on the session’s status.

If the session is still valid, the journey can proceed with specific actions tailored to your business logic.

For example, you might display a redirection message and automatically authenticate the user without requiring their credentials, or if using MFA, only require their username for a lighter login experience. If the session has expired, the user will be prompted to re-authenticate by entering their credentials.

SSO journey

The SSO Service leverages the flexibility of orchestration journeys. When configuring your SSO Service, you need to specify which SSO journey to execute for each client group. This allows you to define logic for grouping relying parties with similar behaviors and shared login processes into the same SSO group.

SSO journeys have additional features compared to client SDK journeys and are the only journeys compatible with the SSO Service.

To learn more about the native logic of SSO journeys, see our dedicated SSO journey overview. For an example of an SSO journey, see our SSO tutorial.

To create an SSO journey, go to the Orchestration section, select Journeys, and click Add blank journey. Then, choose the SSO-Journey type.

Once the journey is created, it can be associated with client groups in SSO Service > Service Definition > Client Groups.