Associate users with risk actions

Mosaic enables you to build a continuous risk profile for the user by binding reported actions to the user context in addition to device. This helps improve risk assessment while reducing unnecessary traction for trustworthy users.

User authentication status

Depending on the user journey, when an app triggers an action (for example, using Trigger action event API), the user can be:

  • Anonymous : The user is unknown . For example, the action was triggered on the page load before the user attempted to log in. In this case, the user is irrelevant and cannot be taken into account for risk analysis.
  • Unconfirmed : The user hasn't authenticated yet but your app has enough information (e.g., a username entered by the actor) to start building a profile. The claimed_user_ID passed to Mosaic represents who this user likely is or who they pretend to be.
  • Confirmed (logged-in) : the user has fully authenticated (including, for example, any required 2FA that was done), their identity is known and mapped to the user ID in your system. In this case, user_id passed to Mosaic is the actual ID of the user in your system.

Lifecycle: Binding user to device session

Fraud Prevention triggers user actions and obtains recommendations within the device session. Device session uniquely identifies a user's device to Mosaic, enabling continuous communication with Fraud Prevention services for telemetry and event collection. Reporting the user's claimed ID or user ID builds an association between the user and their actions within the device session, which allows building a more reliable risk profile. Since a device session isn't related to a browser session or a user session, etc., multiple users can share the same device session.

Depending on the app logic and implementation chosen, a developer can decide when and how to specify the user. A typical user binding lifecycle would be:

  1. Unknown user : The user isn't known yet and cannot be bound to the session.
  2. Claiming the user : The user hasn't authenticated yet but their ID was claimed for events. At this point, the user isn't associated with the device session because their identity hasn't been proved by authentication.
  3. Setting the user : Once the user successfully authenticates, the user is set for this and all subsequent events in the device session until the user is cleared. For example, the user has successfully loggen in your shopping app. Mosaic will automatically associate user's next actions, such as adding items to cart, checkout, and transactions, with their user ID.
  4. Clearing the user : The user gets cleared once the device session expires, or when app requests them to re-login, or if the user gets explicitly cleared. To set the user again, the app has to report the user ID at their next login event.
UserYour appFraud Prevention SDKMosaicGo to login pageInitialize & start device sessionReturn session_tokenTelemetryRegisterTrigger action (backend API) & claim user IDGet recommendation (backend API)"Allow" recommendationLoginTrigger action (backend API) & claim user IDGet recommendation (backend API)"Allow" recommendationLogin successful!Report action result & set user for session (backend API) "Login" action & result "success"CheckoutTrigger action (backend API)(bound to user)Get recommendation (backend API)"Allow" recommendationLog outClear user in device sessionUserYour appFraud Prevention SDKMosaic

Claim the user

Mosaic recommends reporting a claimed user ID as early as possible to build an association between the user and action, before the user identity is confirmed through authentication. Claiming the user helps trace user behavior patterns prior to login and identify vulnerable accounts faster.

For example, the user entered the username and the app was able to map it to the existing user ID in your system. In this case, the claimed_user_ID represents who this user likely is or pretends to be (for example, in case of account takeover attack). If the claimed user successully authenticates, the action events associated with this user while they were still unconfirmed will be merged with events reported later. If the claimed user fails to authenticate, the claimed user ID can be used in further investigation and attack analysis as it can indicate that the account is at risk.

If inout doesn't resolve to any user identifier in your system, claiming the user is still recommended. For example, it helps identify attackers who are using brute force methods to gain access to accounts.

In case the app leverages different identifiers in different flows, you can specify the type of the claimed user ID to enhance risk processing and its accuracy (e.g., email, phone number or SSN).

Note

User identifiers should be opaque and must not include personal user identifiers, such as email, in plain text.

You can report a claimed user ID using the following methods, depending on the SDK or API you are working with:

Copy
Copied
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    get_recommendation: 'false'
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/risk/v1/action/trigger-action?${query}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <YOUR_JWT_HERE>'
      },
      body: JSON.stringify({
        session_token: '[SESSION_TOKEN]',
        action_type: 'login',
        claimed_user_id: '[CLAIMED_USER_ID]', // ID of the user who they claim to be
        claimed_user_id_type: '[CLAIMED_USER_ID_TYPE]', // Pass in case of different types of claimed_user_id's used in different flows
        correlation_id: '[CORRELATION_ID]'
      })
    }
  );

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

run();

Set the user

Setting the user binds the specified user ID to the action, and in some cases, to all subsequent actions in the device session. Depending on your implementation, there multiple points when the user ID can be passed to Mosaic:

From the client side:

  • During client SDK initialization, provided that user identity is known. Only for Web SDK, Android SDK, iOS SDK. This sets the user for all subsequent requests coming from this device in the current device session, or until this device needs to login again as part of the application flow, or until the user is explicitly cleared.
  • via Set user SDK call from the client. This sets the user for all subsequent requests coming from this device in the current device session, or until this device needs to login again as part of the application flow, or until the user is explicitly cleared.

From the backend:

  • Via Trigger action event API call, provided that the user is confirmed. Reporting user_id at this time only sets the user for the triggered event and not for subsequent events.
  • (Recommended) via Report action result API call. Reporting user_id on an successful authentication event sets the user for all subsequent requests coming from this device in the current device session, or until this device needs to login again as part of the application flow. On the other hand, reporting the user for other actions (transactions, checkout, and other action types ) sets the user for a specific event only (by action_token ), but doesn't stick the user ID to the device session. For example:
Note

User identifiers should be opaque and must not include personal user identifiers, such as email, in plain text.

Copy
Copied
import fetch from 'node-fetch';

async function run() {
  const resp = await fetch(
    `https://api.transmitsecurity.io/risk/v1/action/result`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <YOUR_JWT_HERE>'
      },
      body: JSON.stringify({
        action_token: 'login', // Only login actions allows setting the user
        result: 'success', // Indicates the login was successful
        user_id: '[USER_ID]', // The user to set for all subsequent events in the device session
      })
    }
  );

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

run();

Clear the user

The user gets automatically cleared in the following cases:

Note

Reporting the logout action does not automatically clear the user.