Device Binding node

Allows users to register one or more devices to their account. A user can bind multiple devices, and each device can be bound to multiple users.

You must ensure you authenticate the user and obtain their username in the journey before attempting to bind a device.

Registered devices share device data in the form of a public key and a key ID which AM stores in the user’s profile, or you can save it in transient state for processing.

The private key of the keypair is kept safely on the device and secured with biometric security or a PIN.

Compatibility

Product	Compatible?
Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Compatible?

Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Dependencies

You can verify possession of bound devices by using the Device Signing Verifier node.

You can save the device data to the user’s profile by using the Device Binding Storage node.

To use Android Key Attestation, you must also configure the Android Key Attestation Service.

Configuration

Property Usage

Authentication Type

Specifies how the device should secure access to the private key.

The available options are:

Biometric only

Request that the client secures access to the cryptography keys with biometric security, such as a fingerprint.

Biometric with PIN fallback

Request that the client secures access to the cryptography keys with biometric security, such as a fingerprint, but allow use of a PIN if biometric is unavailable.

Application PIN

Request that the client secures access to the cryptography keys with an application-specific PIN.

The PIN is not linked to the user’s device PIN and is stored only on the client device.

The PIN is not sent to AM, so if the user forgets their PIN, they must bind the device again.

None

Allow the client device to create the cryptography keys without securing access to them.

Application IDs

Specifies a list of Android package names and iOS bundle IDs of applications that are allowed to perform device binding.

For example, com.example.app.

Title

Specifies a title to display to the user when asking them to bind the device.

Sub Title

Specifies a subtitle to display to the user when asking them to bind the device.

Description

Specifies descriptive text to display to the user when asking them to bind the device.

Maximum Saved Devices

Specifies the maximum number of devices stored in the user’s profile.

Set this property to 0 if you do not want to limit the number of devices.

When this property is greater than zero, the Exceed Device Limit outcome path becomes available.

Timeout

Specify the number of seconds to wait for a response from the client during binding.

If the specified time is reached, evaluation continues along the Timeout outcome path.

Android Key Attestation

Use Android key attestation to increase confidence that the keys used by the bound device are valid, haven’t been revoked, and use hardware-backed security storage.

The attestation data is also stored in the transient state of the tree, in a variable named DeviceBindingCallback.ATTESTATION, so that you can access and parse the data in a scripted node if required.

For information on the contents of the attestation data JSON response, refer to Attestation certificate in the Android documentation.

Store Device Data in Transient State

If enabled, the node does not save device data in the user’s profile when it completes successfully.

Instead, the node places the device information into the transient state in a variable named DeviceBindingNode.DEVICE. This allows subsequent nodes to use, parse, or alter the information before saving it.

Use the Device Binding Storage node to save the device data to the user’s profile.

Example device data

{
  "uuid": "0ea44aa7-ef55-431b-885b-8c3a87e93331",
  "recoveryCodes": [],
  "deviceName": "Pixel 7 Pro",
  "deviceId": "aaddfecd9b8b3e2a-153cae31c23bc51a8db6d71bc3a31423a6aca97d",
  "createdDate": 1694787036658,
  "lastAccessDate": 1694787036658,
  "key": {
    "kty": "RSA",
    "kid": "0ea44aa7-ef55-431b-885b-8c3a87e93331",
    "use": "sig",
    "alg": "RS512",
    "n": "n7nn76rmgcOGfuVm8N-wur4GgWW-Iek0edwcQR865L3sjKON3XUCHi210tqMyc-PWlCaY-dHisyy7TxK0jn4poui_aK3lnGYNzJpuyTU1-sunSTRVMW8vDTEJxUNQMZFS086_8hVFiC9OnElkpFllp2jzfgZ7u318bdVMgib2bHlscyMo8CZEwA_MHKteIkSD7CZIHMjm-JlJIrKlaLIJ3lkZTUG29g2J9LvdGTMXyt206ZLQw3kAQ_QczHpiKieAiLd9sHydjB7BqGpgCxjCkmqVi4BEvMl8sEEFnpZG1NzjrCBnGfSWr83dzenr6tbdCh5iew-BIdDXXaDPOXRew",
    "e": "AQAB"
  }
}

Android key attestation

When binding a device running Android N (24) or newer, you can use Android key attestation to increase confidence that the keys used by the bound device are valid, have not been revoked, and use hardware-backed security storage.

The ForgeRock SDK for Android generates attestation data for the cryptographic keys it uses for device binding. Using information provided by Google, including a certificate revocation status list (CRL) and hardware attestation root certificate, the node can verify that the certificates are trustworthy.

If you enable the Android key attestation property and the device is running an earlier Android version, evaluation continues down the Unsupported outcome path.

Android key attestation is not supported if you select Application PIN in the Authentication Type property. Evaluation continues down the Unsupported outcome path in this case.

The node does not attempt attestation when binding non-Android devices.

Outputs

If you enable the Android Key Attestation property, the node outputs attestation data in a variable named DeviceBindingCallback.ATTESTATION.

If you enable the Store Device Data in Transient State property, the node outputs device data in a variable named DeviceBindingNode.DEVICE.

Outcomes

Success
Failure
Exceed Device Limit
Unsupported (Client)
Abort (Client)
Timeout (Client)

If the user successfully binds their device, evaluation continues along the Success outcome path.

If AM encounters an issue when attempting to register using a device, evaluation continues along the Failure outcome path.

If the Maximum Saved Devices property is set to an integer greater than zero, and binding a new device would take the number of devices above the specified threshold, then evaluation continues down the Exceed Device Limit outcome path. In this case, you need to instruct your users to log in with an existing bound device in order to remove one or more of their registered devices.

If the user’s client does not support the requested operation, evaluation continues along the Unsupported outcome path. For example, the node is configured to require biometric authentication, but the device does not provide support.

If the user cancels the attempt to bind a device, evaluation continues along the Abort outcome path.

If the node does not receive a response from the user’s device within the Timeout specified in the node configuration, evaluation continues along the Timeout outcome path.