Manage devices

Mosaic provides a solution for managing devices as part of identity management. In this article, you'll learn how to implement basic device management tasks, such as identifying a returning device or deleting a device that is no longer in use. For more about the Device entity concept, see How devices work.

You can view devices in the Admin Portal (Admin Portal > B2C Identity or B2B Identity > Users > user > Devices). In the Admin Portal, switch between two views:

• Device view includes device entity-related data: device type, device ID, display name, status, last authentication timestamptetc.
• Device keys view includes details on the cryptographic keys residing on the devices and enriched with Fraud Prevetion data: device type, vendor device ID coming from the Fraud Prevetion (if available), browser, last activity, status, custom data, etc.

Additional details such as hardware model, OS, browser, and registration metadata (IP address, region) are also stored when available and can be obtained from the journey context.

Add a new device entity and establish a strong association between a device and a user using crypto-binding. After authenticating a user or onboarding a new user, include the Register or Update Device step in the journey. During device registration, the SDK generates a cryptographic key pair on the device without requiring user interaction—though you can request the user's consent if needed. The device's public key is then exported and sent to Mosaic, while the private key remains securely on the device. As a result, Mosaic creates a Device entity. The step returns the device_id, which uniquely identifies the Device entity. You can provide it externally or let the SDK generate it.

In the example journey below, the Register or Update Device step is added after password authentication. After registering a device, Mosaic returns a device_id and associates a device with the logged-in user.

Identifying known devices early in a journey enhances security and allows you to build tailored user experiences. To check if this is a returning device, add the Known Device Status step to your journey. This step checks if the device is registered to a specific user in the app and branches based on the device's status.

The validation process involves Mosaic matching a user with a device and issuing a challenge to the client to sign using the private key stored on the user's device. This process is handled implicitly by the client SDK and no user interaction is required. If the device is recognized, the step returns the device information, populates journey context, and branches as follows:

• Yes (Known): the device is registered and associated with the user. The journey can proceed normally.
• No: the device is not associated with this user, is suspended, or an error occurred. You can design the journey to register the device, prompt additional verification, or reject access.

You can use this step as part of two-factor authentication, leveraging something the user has (their device) in addition to something the user knows (such as a password). You can also use it to elevate trust for known devices and reduce user friction.

For example, your app allows logging in via registered devices only. Add the Known Device Status step after the Collect Information step.

Since the user isn't known yet, set the user authentication state to "The user is not authenticated", and have the journey obtain a user identifier provided in a previous step.

If the device is recognized and active, the journey allows the user to proceed to login. If the user tries to access the app from an unknown device, the journey rejects access.

Mosaic allows you to enrich the Device entity with additional data. This can be helpful if you're looking for a way to provide a customized user experience depending on which device the user is currently using. You can configure journeys to read information from the device entity and proceed accordingly.

For example, a user wants to distinguish between their devices. To provide a user-friendly name for the current user's device, add the following steps to the journey:

1. Start by validating if the device is registered to the authenticated user by adding Known Device Status. If the device is recognized, the device information becomes available in the journey.
2. Add the Collect information step to collect input from the user. For example, add the device_name string field to the schema. Once the user submits the name, it will be stored as device_name in the output variable clientData.
3. Add the Register or Update Device step to update the device entity. Set device_info.device.device_id as Device ID and clientData.device_name as Display name.

For example, a user wants to distinguish between their devices. To display a device name for the current user's device, add the following steps to the journey:

1. Start by validating whether the device is registered to the authenticated user by adding Known Device Status. If the device is recognized, the step returns information about the device.
2. Add the Condition step to act depending on the device name returned by the previous step. For example, to check if the device name is "My work cellphone", use device_info.device.display_name == "My work cellphone" expression. Alternatively, check for a device type (device_info.device.device_type == "mobile") and branch accordingly.
3. Display "It's a work cellphone" using the Display Information step if true.

All authentication journey steps accept a Device source. By default, authentication steps pick up the device_id from journey context automatically after any device operation earlier in the journey. You can also provide it explicitly.

When device information is available, Mosaic records the device_id and device ownership (user-owned or non-user-owned) alongside every authentication event. Authentication outcome is not affected — device context enriches observability and enables adaptive logic.

For example, you want to surface an extra verification step when a user's password is used from a device not registered to their account.

1. Add Known Device Status right after the Login Form. This populates the device object in journey context, including the device_id.
2. Add the Password Authentication step. The journey proceeds to it irrespective of device status. The Device source (including device_id) is obtained from the journey.
3. Add a Condition step that checks whether the logged-in user matches the device owner (@policy.userContext().user_id == device_info.device.user_id). If yes, complete the journey. If the user logged in from a new device, route the journey to notify them about the unknown device and add an additional OTP verification step before completing.

Keeping an inventory of devices linked to a user is helpful if you want to enforce policies, such as limiting the number of devices per user or implementing a single-device policy. The Get User Devices step returns a list of a user's devices with information about each device.

For example, your company is about to enforce a single-device policy. Before limiting access from multiple devices, you might want to let users check how many devices they have and display their names. Add the following steps to your journey to count user devices and act accordingly, depending on the result.

1. Add the Get User Devices step to retrieve a list of all devices for a user. The step requires a user identifier as an input. Since the user has already authenticated, the journey holds information about the user in the user context. This step returns an array of Device objects filtered by user.

2. Add the Condition step to evaluate the output. In this example, the @std.len(userDevices) == 1 condition checks whether the user has exactly one linked device, based on the result returned by the previous journey step. Depending on the output, you can customize a message for the user.

Suspending devices is crucial for establishing strong security and privilege management. You might want to permanently restrict a malicious device from accessing your app resources, or temporarily suspend an employee's work device while not in use.

Add the Suspend Device step to your journey, or suspend devices directly in the Admin Portal. Suspending a device changes its status to Suspended and also blocks its linked device cryptographic keys and locks device-bound authenticators (mobile biometrics and PIN).

Unlike deleting a device, suspending a device keeps the Device entity associated with the user. A suspended device is visible in the Admin Portal and can be discovered using the Get User Devices journey step. Suspended devices fail validation performed by Known Device Status—they are routed to the No branch rather than the success path. Suspended devices can also be reactivated if necessary.

When a suspended device needs to be restored, for example, when a lost device is recovered or a temporary restriction is lifted, use the Reactivate Device step or reactivate directly in the Admin Portal. This restores the device to the Active status, activates its linked device cryptographic keys, and unlocks its device-bound authenticators that were locked as a result of the suspension. Authenticators that were independently locked before the device was suspended remain locked.

Deleting a device is the final step in its identity lifecycle. Deleting irrelevant devices enhances security and provides visibility into identity management. For example, you might want to delete a device that is no longer in the user's possession, or if you enforce a single device policy that doesn't allow users to access your app from several devices.

The Delete Device step removes the Device entity from the user record. The next time the user tries to log in from this device, it will appear as new. Optionally, you can also delete device-bound authenticators (mobile biometrics and PIN) linked to the device.

The example journey ensures the user can only have one device by registering a new device and removing the other device.

1. Start by validating if the device is registered to the authenticated user by adding Known Device Status. If the device is recognized and active, the journey completes.

2. In the case of a new device, retrieve the user's other devices. Add the Get User Devices step to retrieve a list of all devices for a user. This step returns a userDevices array of Device objects filtered by user.

3. Add the Condition step to evaluate the output. In this example, the @std.len(userDevices) > 0 condition is used to check if the user has another device linked to their account.

4. Remove the previously registered device by adding the Delete Device step. Specify the device IDs to delete using the let extractDeviceId = (device) => device.device_id return @std.map(userDevices, extractDeviceId) expression.

5. If there are no devices associated with the user, register the current device with the Register or Update Device step.

Create adaptive device management flows based on risk assessment data provided by Mosaic Fraud Prevention. See Secure device identity for more information. Elevate trust and reduce friction for known and trustworthy devices, enforce step-up authentication in response to risky device activity, and suspend malicious devices based on risk analytics.