Manage sessions for backend authentication

Manage backend sessions to authenticate users and issue new tokens without unnecessary user interaction that provides a better identity experience with no cost to security (see Session management).

Backend sessions are created as a result of backend authentication. While the session is valid, you can leverage it to silently authenticate users. Backend sessions can be shared among multiple backend authentication methods which makes it possible to implement secure scenarios such as Backend multi-factor authentication and single sign-on across the apps.

Common use cases that rely on the session management:

• Silent authentication within the context of the same app or across apps (SSO)
• Multi-factor authentication

Create sessions

Upon completing the backend authentication process, Mosaic creates a backend session and your server receives a response that includes an access token, ID token, refresh token, and the session ID (session_id) of the new session.

{
  "access_token": "string",
  "id_token": "string",
  "refresh_token": "string",
  "token_type": "string",
  "expires_in": 3600,
  "session_id": "string" // Session ID of the created session
}

Validate tokens

The access token is a JWT (Json Web Token) signed by Mosaic (see Token reference for the claim structure). We strongly recommend validating it using these guidelines before you can use it to grant the user access.

Here's an example of a decoded token:

{
  "tid": "",
  "app_name": "Acme",
  "app_id": "8flFllgrd1Wqiru4IGai0",
  "roles": [
    "smP3MD65l7hKXG6qJ-S5d"
  ],
  "jti": "IJMTqbmijVG7_LsJz-y5U",
  "sub": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
  "iat": 1658056533,
  "exp": 1658060133,
  "scope": "offline_access",
  "client_id": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
  "iss": "https://userid.security",
  "aud": "userid-api"
}

Store session

Once the access token is validated, you'll need to store the access token and the session ID so that they can be used to grant access in subsequent requests.

Extend access

When a user returns to your website, you'll want to try to provide them access without requiring them to login. Implement the following session management logic that determines the user's eligibility to login without authentication.

Start by checking for a session cookie, which indicates a local session already exists. If not found, redirect the user to login. If found, send the cookie to your backend and use it to retrieve the tokens.

• If the access token is still valid, you can allow the user to continue to your website without having to login again.
• If the access token has expired, delete the cookie and prompt the user to login. Alternatively, try authenticating a user silently based on an existing IDP session.

Add authentications to a session

You can add multiple authentication methods within the context of the same session. To do this, specify the session ID in the subsequent authentication request. It allows supporting scenarios like Multi-factor authentication. New authentication extends the session lifetime.

The example below demonstrates a magic link authentication request used as a second factor in MFA.

import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    `https://api.transmitsecurity.io/cis/v1/auth/link/email/authenticate`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer [TOKEN]' // Client access token
      },
      body: JSON.stringify({
        session_id: '[SESSION_ID]', // Session ID of the active session
        code: '[CODE]' // Code returned to your redirect URI
      })
    }
  );

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

run();

Logout sessions

Logging out immediately terminates a session even if it hasn't expired yet. Use Logout API to revoke a session.

import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    `https://api.transmitsecurity.io/cis/v1/auth/session/logout`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer [TOKEN]' // Client access token
      },
      body: JSON.stringify({session_id: '[SESSION_ID]'}) // ID of the session to terminate
    }
  );

  if (resp.status === 204) {
    console.log('success');
  } else {
    const data = await resp.json();
    console.log(data);
  }
}

run();