Integrate login using PAR

Pushed authorization request (PAR) is a secure way to initiate the OIDC authorization flow. Unlike a regular OIDC flow where auth parameters are sent in the query right in the browser, PAR allows sending them as backend request which makes the authorization process protected against tampering.

How it works

When a user requests to log in, the client passes this request to the backend that starts the flow by sending a request to the PAR endpoint (Step 3). The request includes all the parameters needed for OIDC authorization. In response, Mosaic returns a request_uri which is a reference to the PAR object registered in Mosaic. The backend forwards the request_uri to the client. The client then sends the OIDC authorization request to Mosaic with request_uri (Step 4). Upon authenticating the user, Mosaic redirects back to the Redirect URI with the authorization code. Your app exchanges the authorization code for user tokens in the backend (Step 5). After validating the user tokens, your app logs in the user (Step 6).

Below is an example of a login flow leveraging PAR that can be implemented using the steps in this guide. Mosaic APIs are shown in pink along with the relevant integration step, described below.

Step 1: Set up login method

Before you add login to your application, set up the login method you plan to use by completing the provider-specific setup, as described in these dedicated guides:

• Google : Set up Google credentials and consent screen using steps 1-3
• Apple : Set up Apple credentials using steps 1-2
• Facebook : Set up Facebook credentials using steps 1-2
• LINE : Set up LINE credentials using steps 1-2
• Authentication Hub : Set up an app using step 1
• Hosted login

Alternatively, you can use the SSO Service by Mosaic.

Step 2: Configure client settings

1. After authentication is completed, the authentication result is returned to the redirect URI. This URI should be registered in client settings in the Mosaic Admin Portal.
   • For pure OIDC implementation: from the Admin Portal under Applications , click your application and proceed to the client settings to enter this URI under Redirect URIs . If you don't already have an application, you'll need to create one first (see Create application ).
   • If using SSO Service: from the Admin Portal under SSO and Federation , navigate to Configuration > Client groups and proceed to the client settings to enter this URI under Redirect URIs .
2. Optionally, enforce PAR for all authentication requests invoked by your client.

Step 3: Create PAR object

On the backend, start the flow by sending a POST request to the /oidc/request with OIDC auth parameters in the request body. The response returns request_uri—it references the object stored by Mosaic which includes all auth parameters for a specific client.

Here are some auth parameters that can be sent in the PAR request (see PAR API Reference):

Below is a sample request to log in with hosted login:

import fetch from 'node-fetch';

async function run() {
  const formData = {
    client_id: 'CLIENT_ID',
    client_secret: 'CLIENT_SECRET',
    redirect_uri: 'REDIRECT_URI',
    response_type: 'code',
    prompt: 'consent',
    scope: 'openid offline_access'
  };

  const resp = await fetch(
    `https://api.transmitsecurity.io/cis/oidc/request`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams(formData).toString()
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

Step 4: Authorize user

Authorize the user by sending a GET request to /oidc/auth with redirect_uri and client_id. This will initiate an OIDC authorization code flow with the parameters you've already submitted to Mosaic in Step 3. The request_uri can only be used with the same client that originally sent a request to PAR endpoint (/oidc/request) and only before its expiration time (60 seconds).

This endpoint returns an authorization code to your redirect URI upon successful authentication; otherwise, an error.

// Line breaks and spaces were added for readability
  https://api.transmitsecurity.io/cis/oidc/auth?
    client_id=CLIENT_ID&
    request_uri=REQUEST_URI

Step 5: Get user tokens

The authorization code returned to your redirect URI upon successful authentication should be passed to your app backend. Your server can exchange this code for an ID and access token by sending a POST request like the one below to the /oidc/token endpoint, along with the following parameters:

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

Step 6: Validate tokens

The /oidc/token response includes an ID token with user profile data, and a user access token. These tokens must be validated as described here. Validate the token signatures using the public key retrieved from this request:

curl -i -X GET \
  'https://api.transmitsecurity.io/cis/oidc/jwks'

Step 7: Refresh access tokens

If the app has to keep operating on the user's behalf after the user has left, you can obtain a user access token using the refresh token, i.e., to extend access of logged-in users when the access token has expired. Both of these tokens are returned upon successful authentication (if offline_access is requested). To do this, send a POST request to the /oidc/token endpoint, along with the following parameters:

curl -i -X POST \
https://api.transmitsecurity.io/oidc/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d grant_type=refresh_token \
-d client_id=CLIENT_ID \
-d client_secret=CLIENT_SECRET \
-d refresh_token=REFRESH_TOKEN