Hosted login deployment

Deploying a hosted login to your application implies integrating the OIDC authentication logic and customizing your authentication flow and methods.

This guide shows how to deploy OIDC-based, single-factor authentication into your application using your Mosaic's default authentication settings. Customize your authentication experience following the Next steps.

How it works

Mosaic supports the OIDC authorization code flow for user authentication and the OIDC RP-initiated logout for logout.

Here's an example of a login flow that can be implemented using the steps in this guide. Mosaic APIs are shown in pink along with the relevant integration step, described below. Note that logout isn't shown.

  1. The user requests to log in and your app sends an authorization request to Mosaic ( Step 3 ).
  2. Mosaic redirects to the hosted login experience to authenticate the user.
  3. If successful, Mosaic redirects back to your app with an authorization code.
  4. Your app exchanges the authorization code for user tokens in the backend ( Step 4 ).
  5. After validating the user tokens, your app logs in the user.

Step 1: Create redirect URI

Create the redirect endpoint that will receive an authorization code. This code will later be exchanged for an ID and access token. The redirect URI should accept code as a query parameter. For example, if https://domain.com/verify is your redirect URI, then Mosaic will redirect to https://domain.com/verify?code=123abc.

The redirect endpoint should then use the oidc/token route to get an access token for the user (as described in Step 4).

Step 2: Add redirect URI to app

Add the redirect URI (e.g., https://domain.com/verify) as an allowed redirect URI for your Mosaic application. This will also be the redirect_uri that you'll need to pass in the initial request. The redirect endpoint should then use the oidc/token route to get an access token for the user (as described in Step 4).

From the Admin Portal under Applications, click on your application to edit your application settings and add this URI under Redirect URIs. If you don't already have an application, create a new application.

Step 3: Initiate login flow

Use a request like the one below to initiate a login flow. The client_id and redirect_uri correspond to the ones in the application settings in Mosaic's Admin Portal.

Note

Upon successful authentication, the browser will be redirected to the redirect URI along with a code to exchange for tokens in the next step. For example, if https://domain.com/verify is your redirect URI, then Mosaic will redirect to https://domain.com/verify?code=123abc. However, if an authentication error occurs, the redirect URI will contain the error instead.

Copy
Copied
// Note: line breaks and notes were added for readability
https://api.transmitsecurity.io/cis/oidc/auth? 
  client_id=CLIENT_ID&  // Client ID from the Mosaic app setting
  redirect_uri=REDIRECT_URI&  // Redirect URI created in Step 1
  scope=openid&
  response_type=code&
  prompt=consent // Consent will be granted automatically
NOTE

To learn how to initiate login for B2B scenarios, see Login members into B2B apps.

Step 4: Get user token

To exchange the code received from Mosaic for an ID and access token, your server should send a POST request like the one below to the Mosaic /oidc/token endpoint. Replace placeholders with the code you received in Step 3, your redirect URI, and your client credentials that can be found in your application settings from the Mosaic Admin Portal.

IMPORTANT

This request returns user tokens that should grant user access to your resources. Before granting access, verify the tokens' validity, ensuring it was generated by Mosaic, is still valid, and is associated with the user. To know more, see Validate tokens to protect your APIs.

Copy
Copied
curl -i -X POST \
  https://api.transmitsecurity.io/oidc/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d code=CODE \
  -d grant_type=authorization_code \
  -d redirect_uri=REDIRECT_URI

Next steps

Once you've completed a basic deployment, you can consider: