# Launch OIDC SSO with the Mosaic-hosted experience

Note
This page guides you through integrating your app with the Mosaic SSO Service using OIDC, assuming you're using the Mosaic-hosted experience. If you're building your own SSO page, be sure to also read [this guide](/guides/user/sso_orchestration/sso_quickstart_selfhosted_ui).

When you integrate OIDC-based SSO using the Mosaic-hosted experience, your clients need to start an OIDC authentication flow and exchange the code for tokens once the flow is completed. This page provides insights into the interaction between your system and Mosaic during an SSO flow.

## Before you start

Before you start the integration, you need to have the [SSO Service](/guides/user/sso_orchestration/sso_config_service) and [SSO journeys](/guides/user/sso_orchestration/sso_journeys) configured.

If you're using the Mosaic-hosted experience and want to customize its branding and styling to match your app's visual identity, see [Manage styling for the Mosaic-hosted SSO experience](/guides/platform/hosted_ui_styles).

## How it works

Mosaic supports the [OIDC authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) for user authentication. Integrating SSO using the Mosaic-hosted experience involves initiating an authorization process to Mosaic's OIDC endpoint from your application. This triggers the SSO journey. When the journey ends, Mosaic returns an authorization code to your redirect URI, which your client exchanges for tokens, marking the user as logged in. Mosaic APIs are shown in pink along with the relevant implementation steps.

```mermaid
sequenceDiagram
  participant User
  participant Client
  participant Mosaic
  participant HostedExperience as Mosaic-hosted experience
    User-->>Client: Request login
    Note right of Client: Step 1
    Client->>Mosaic: Authorize user with `/oidc/auth`
    Note left of Mosaic: Step 2
    Mosaic-->>HostedExperience: Redirect
    HostedExperience --> Mosaic: Run journey logic
    HostedExperience-->>Mosaic: Redirect
    Note right of Client: Step 3
    Mosaic->>Client: Redirect to URI with code
    Client->>Mosaic: Get tokens
    Mosaic->>Client: User tokens
    Client-->>Client: Validate tokens
    Client-->>User: Logged in
```

## Step 1: Create a redirect URI

Create the redirect endpoint for the relying party that will receive an authorization code when the SSO authentication is completed. This code will be exchanged for user tokens, as described in  [Step 3](#step-3-get-user-tokens). The redirect URI should accept `code` as a query parameter. For example, if `https://domain.com/verify` is your redirect URI, Mosaic will redirect to `https://domain.com/verify?code=123abc` when the centralized login flow is complete.

Note
If an authentication error occurs, the redirect URI will contain an `error`query parameter with information about the error as value.

## Step 2: Request centralized login

When a user requests to log in, send a centralized login request like the one below (Step 1). In this  [OIDC authorization](/openapi/user/oidc.openapi/other/oidcauthenticate) call, pass your client ID, and the redirect URI.

Sending the centralized login request corresponds to triggering the SSO login journey in Mosaic (Step 2). Once the SSO login is completed, an authorization code is returned by Mosaic to the requested redirect URI in the `code` parameter. This code will be exchanged for a token in the next step.

```js
let url = new URL("https://api.transmitsecurity.io/cis/oidc/auth?&response_type=code&prompt=login&scope=openid%20email");
url.searchParams.append("client_id", YOUR_CLIENT_ID); // Client ID from the client settings in the SSO Service
url.searchParams.append("redirect_uri", YOUR_REDIRECT_URI); // Redirect URI set in the client settings in the SSO Service
window.location = url.toString();
```

## Step 3: Get user tokens

To obtain an ID and access token, your server can send a request like the one below to the [OIDC token](/openapi/user/oidc.openapi/other/oidctoken) endpoint. Replace placeholders with the code you received in [Step 2](#step-2-request-centralized-login), your redirect URI, and your client credentials that can be found in your SSO client group settings (**Admin Portal** > **SSO and Federation** > **Configuration** > **Clients groups**).

Note
Returned tokens must be validated as described [here](/guides/user/validate_tokens).

```shell
curl --location --request POST 'https://api.transmitsecurity.io/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=CODE' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=REDIRECT_URI'
```

## Step 4: Log out user

To log out, the browser sends a POST request to the IDO’s `/ido/api/v2/auth/sso-logout` endpoint. The server will infer the SSO sessions from the cookie, delete the associated sessions, and return a response that instructs the browser to delete the cookies as well.

The SSO model allows multiple SSO sessions per browser, each correlating with a Clients-Group.

By default, the logout endpoint logs out all existing SSO sessions. To log out of a specific Clients-Group, include the group’s ID as the value of the `clientsGroupId` query parameter.

## Discovery

If needed, information for configuring Mosaic as an OIDC IDP is available using the discovery endpoint, including Mosaic OIDC endpoints and supported parameters. Send the following request:

```shell
curl -i -X GET \
  'https://api.transmitsecurity.io/cis/oidc/.well-known/openid-configuration'
```

Note
Cache returned metadata for further reuse to avoid reaching API rate limits.