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 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: |
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: |
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
Default: false |
Custom Matching Script |
Select the custom script to use when Use Custom Matching Script is enabled. Only scripts of type
Default: |
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.