Identity Cloud

Device Match node

The Device Match node compares any collected device metadata with that stored in the user’s profile.

Use this node with the Device Profile Collector node to check whether the user is authenticating with a previously saved, trusted device.

You can choose between two methods of comparison:

  1. Built-in matching

    The node handles the comparison and matching. You configure the acceptable variance and the maximum age for device profiles.

  2. Custom matching

    Create scripts to compare captured device data against trusted device profiles.

    AM includes a template script you can customize to your requirements. In the Identity Cloud admin UI, go to Scripts > Auth Scripts, and click Device Profile Match Template - Decision Node Script.

    ForgeRock also provides a more complete sample script, as well as instructions for its use and a development toolkit. Find these resources on GitHub at https://github.com/ForgeRock/forgerock-device-match-script.

You must establish the identity of the user before attempting to match device profiles.

Compatibility

Product Compatible?

ForgeRock Identity Cloud

Yes

ForgeRock Access Management (self-managed)

Yes

ForgeRock Identity Platform (self-managed)

Yes

Inputs

Use a Device Profile Collector node prior to this node to collect metadata for the current device. This node reads the collected device metadata from the shared node state.

If Use Custom Matching Script is enabled, the inputs depend on the script.

Dependencies

The journey must establish the user identity before invoking this node. This node uses the identity to look up saved device profiles in the user’s account.

If Use Custom Matching Script is enabled, refer to the script for information about dependencies.

Configuration

Property Usage

Acceptable Variance

Specify the maximum number of acceptable device attribute differences for a match.

Default: 0 (all attributes must match)

Expiration

Specify the maximum age in days a saved profile is valid for comparison.

The node ignores older device profiles saved to the user’s account when comparing device profiles with the collected metadata.

Default: 30 (days)

Use Custom Matching Script

Enable this to use the custom script instead of built-in matching to compare the collected metadata with saved device profiles.

When this is enabled, the node ignores the Acceptable Variance and Expiration settings.

The script type must be Journey Decision Node.

Default: false

Custom Matching Script

Select the custom script to use when Use Custom Matching Script is enabled.

Only scripts of type Journey Decision Node appear in the list.

Default: Authentication Tree Decision Node Script

Outputs

This node does not change the shared state on its own.

If the node uses a Custom Matching Script, check the script to review its output.

Outcomes

True

The collected device metadata matches a saved profile within the configured variance.

False

The collected device metadata did not match or another error occurred.

Unknown Device

The user has no saved trusted device profiles, or the user identity hasn’t yet been established.

Errors

This node logs the following warning messages:

script outcome error

The script failed to set the outcome field to a string.

error evaluating the script

The script failed to complete. Refer to the logs for details.

Example

The following journey authenticates the user and checks whether the current device is trusted. If the device isn’t trusted yet, the journey requires an additional authentication factor and lets the user opt to trust the device:

Checking whether the current device is trusted
Copyright © 2010-2024 ForgeRock, all rights reserved.