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:

Built-in matching

The node handles the comparison and matching. You configure the acceptable variance and the maximum age for device profiles.
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 AM admin UI, go to Realms > Realm Name > 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

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

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 `Decision node script for authentication trees` (standalone AM) or `Journey Decision Node` (ForgeRock Identity Platform deployment). Default: false
Custom Matching Script	Select the custom script to use when Use Custom Matching Script is enabled. Only scripts of type `Decision node script for authentication trees` (standalone AM) or `Journey Decision Node` (ForgeRock Identity Platform deployment) appear in the list. Default: `Authentication Tree Decision Node Script`

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 Decision node script for authentication trees (standalone AM) or Journey Decision Node (ForgeRock Identity Platform deployment).

Default: false

Custom Matching Script

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

Only scripts of type Decision node script for authentication trees (standalone AM) or Journey Decision Node (ForgeRock Identity Platform deployment) 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:

The Page node with the Platform Username node and Platform Password node prompt the user for their credentials.
The Data Store Decision node confirms the user’s credentials.
The Device Profile Collector node collects metadata about the current device.
The Device Match node compares saved device profiles with the current device.
The Inner MFA Journey, an Inner Tree Evaluator node, requires an additional authentication factor.
The Message node prompts the user with an option to trust the current device.
The Device Profile Save node saves the current device profile.
The Increment Login Count node updates the number of successful authentications.
The Progressive Profile Journey, an Inner Tree Evaluator node, invokes a journey to collect additional profile data.

AM 7.5.0