Auth node reference

Device Location Match node

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

Use this node with the Device Profile Collector node to determine if the authenticating user’s device is located within range of somewhere they have authenticated from, and saved, previously.

Example

The following journey authenticates the user and checks whether the current device is located within ten kilometers of a previously saved device location. If the user doesn’t have a saved device that matches the current device identifier or the device location is outside of this range, authentication fails:

Checking whether the current device is located within range of a previously saved location

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

  • This node requires the username property in the incoming node state.

    Implement a Username Collector node (standalone AM) or Platform Username node (Advanced Identity Cloud and Ping Identity Platform deployments) earlier in the journey.

  • This node reads the collected device metadata from the shared state.

    Implement a Device Profile Collector node earlier in the journey to collect metadata for the current device.

Uniquely identify devices

This 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, this 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

The Device Profile Collector node earlier in the journey must collect the device’s location.

Configuration

Property Usage

Maximum Radius (km)

The maximum distance, in kilometers, that a device can be from a previously saved location.

The distance is calculated point-to-point.

Outputs

This node doesn’t write anything to the shared state.

Outcomes

True

The collected location is within the specified range of saved location data.

False

The collected location isn’t within the specified range of saved location data.

Unknown Device

The user doesn’t have a saved device that matches the current device’s identifier.

Errors

This node doesn’t log messages of its own.