Advanced Identity Cloud

Device Match node

The Device Match node compares 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.

The Device Match node supports the following 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.

    PingOne Advanced Identity Cloud includes a customizable template script. In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts, and click Device Profile Match Template - Decision Node Script.

    For a comprehensive sample script with instructions for its use and a development toolkit, go to the GitHub sample repository.

Compatibility

Product Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

This node reads the username from the shared state to look up saved device profiles in the user’s account. Implement a Platform Username node earlier in the journey to obtain the username.

This node also reads collected device metadata from the shared state. Implement a Device Profile Collector node earlier in the journey to collect metadata for the current device.

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

Uniquely identify devices

The Device Match node looks up a user’s stored device profiles using a device identifier as a key.

The client device generates a device identifier as part of the device profile that it returns to the Device Profile Collector node in the JSON payload.

For example:

{
  "identifier": "d50cdb5ce8d055a3-86bd35e1b975a14d76b40940112c2380264c8efd",
  ....
}

When can identifiers change?

If the identifier changes, the Device Match node can’t match any stored device profiles.

If this happens, your journey must collect and store a new device profile that contains the new identifier.

This section explains what can cause an identifier to change on each platform.

  • Android

  • iOS

  • JavaScript

In Android, the instance ID is deleted or changes if any of the following occurs:

  • An app is restored on a new device.

  • The user uninstalls and reinstalls the app.

  • The user clears app data.

On iOS, the device ID is stored in the Keychain. This means the ID persists when the app is removed.

However, the device ID is deleted or changes if any of the following occurs:

  • The user wipes or factory resets the phone.

  • The user migrates to a new phone.

  • The keychain is programmatically deleted from the phone.

  • The device ID is programmatically deleted from the Keychain.

  • The keychain identifier in the forgerock_keychain_access_group configuration property changes.

In JavaScript, the device ID is deleted or changes if any of the following occurs:

  • The browser window creates the device ID while in "private" or "incognito" mode. Closing the browser removes the ID.

  • The browser removes the ID when cleaning up old data to accommodate new data.

  • The browser is uninstalled and reinstalled. The ID is removed.

  • The user removes the device ID by clearing the browser data.

Dependencies

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

Configuration

Property Usage

Acceptable Variance

The maximum number of acceptable device attribute differences for a match.

Default: 0 (all attributes must match)

Expiration

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 option to use a custom script instead of built-in matching to compare the collected metadata with saved device profiles.

When 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, the output is determined by the script.

Outcomes

True

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

False

The collected device metadata doesn’t match a saved profile, or another error occurred.

Unknown Device

The journey follows this outcome path in the following situations:

  • The user has no saved trusted device profiles.

  • The user identity hasn’t yet been established.

  • The acceptable device variance matches, but the device ID no longer matches.

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