--- title: Device Binding node description: The 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. component: auth-node-ref version: latest page_id: auth-node-ref::device-binding canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/device-binding.html page_aliases: ["auth-node-device-binding.adoc"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/device-binding.html section_ids: example: Example availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration android_key_attestation: Android key attestation outputs: Outputs callbacks: Callbacks outcomes: Outcomes errors: Errors --- # Device Binding node The 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. > **Collapse: What are the differences between device binding/signing and WebAuthn?** > > There are many similarities between WebAuthn and device binding and JWS verification. We provide authentication nodes to implement both technologies in your journeys. > > Both can be used for usernameless and passwordless authentication, they both use public key cryptography, and both can be used as part of a multi-factor authentication journey. > > One major difference is that with device binding, the private key never leaves the device. > > With WebAuthn, there is a possibility that the private key is synchronized across client devices because of Passkey support, which may be undesirable for your organization. > > For details of the differences, refer to the following table: > > **Comparison of WebAuthn and Device Binding/JWS Verification** > > | Feature | WebAuthn / FIDO | Device Binding / JWS Verifier | Details | > | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Industry-standards based | ✅ | ❌ | You can refer to the [WebAuthn W3C specification](https://www.w3.org/TR/webauthn-2/).Device binding and JWS verification are proprietary implementations. | > | Public key cryptography | ✅ | ✅ | Both methods use [Public key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). | > | Usernameless support | ✅ | ✅ | After registration, the username can be stored in the device and obtained during authentication without the user having to enter their credentials. | > | Keys are bound to the device | ❌ | ✅ | With WebAuthn, if Passkeys are used, they can be shared across devices.With device binding, the private keys do not leave the device. | > | Sign custom data | ❌ | ✅ | With device binding, you can:- Customize the challenge that the device must sign. For example, you could include details of a transaction, such as the amount in dollars. > > - Add custom claims to the payload when signing a challenge. This gives additional context that the server can make use of by using a scripted node. > > Refer to [Add custom claims when signing](https://docs.pingidentity.com/sdks/latest/sdks/use-cases/how-to-bind-devices.html#add_custom_claims_when_signing). | > | Format of signed data | [WebAuthn authenticator data](https://www.w3.org/TR/webauthn/#authenticator-data) | [JSON Web Signature (JWS)](https://openid.net/specs/draft-jones-json-web-signature-04.html) | | > | Integration | ❌ | ✅ | With device binding, after verification, the signed JWT is available in:- Audit Logs > > - Transient node stateThis enables the data within to be used for integration into your processes and business logic. | > | Platform support | ✅ Android✅ iOS✅ Web browsers | ✅ Android✅ iOS❌ Web browsers | As it is challenging to store secure data in a browser as a client app, device binding is not supported in web browsers. | > | Authenticator support | Determined by the platform.Configuration limited to:- Biometric with Fallback to Device Pin | Determined by the authentication node.Full configuration options:- Biometric Authentication > > - Biometric with Fallback to Device Pin > > - Application Pin > > - Silent | With device binding, you can specify what authentication action the user must perform to get access to the private keys.This provides greater flexibility in your security implementation and can reduce authentication friction for your users. | > | Key storage | Web browsers and iOS synchronize to the cloud.Android has the option to synchronize to the cloud. | * Android > > KeyStore > > * iOS > > Secure enclave: hardware-backed and not synchronized to the cloud. | Both technologies store the private keys securely on the client.WebAuthn supports synchronizing the private keys to the cloud for use on other devices.This can reduce authentication friction for your users but may also increase the risk of a breach. | > | Managing device keys | Managed by the device OS.Apps cannot delete *local* client keys programmatically and do not have a reference to the *remote* server key for deletion. | Managed by the Ping SDKs.Provides an interface to delete local client and remote server keys. | The ability to programmatically delete both client and server keys can greatly simplify the process of registering a new device if an old device is lost or stolen. | > | Passkey support | ✅ | ❌ | WebAuthn supports synchronizing the private keys to the cloud for use on other devices.Device binding keeps the private key locked in the device. | > | App integrity verification | - Android > > Requires an `assetlinks.json` file. > > - iOS > > Requires `apple-app-site-association` file. | Not provided by the device binding or verification nodes.It can be added as part of the journey by using app integrity nodes. | App integrity verification helps ensure your users are only using a supported app rather than a third-party or potentially malicious version. | > | Key attestation | * Android > > SafetyNet > > * iOS > > None | - Android > > Uses [hardware-backed key pairs with Key Attestation](https://developer.android.com/privacy-and-security/security-key-attestation). > > - iOS > > It can be added as part of the journey by using app integrity nodes to support key attestation. | Key attestation verifies that the private key is valid and correct, is not forged, and was not created in an insecure manner. | > | Complexity | Medium | Low | WebAuthn requires a bit more configuration, for example, creating and uploading the `assetlinks.json` and `apple-app-site-association` files.Device binding only requires the journey and the SDK built into your app. | Registered devices share device data in the form of a public key and a key ID which Advanced Identity Cloud 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. You can verify possession of bound devices using the [Device Signing Verifier node](device-signing-verifier.html). Learn more about using this node with the Ping SDKs for Android and iOS in [Implement device binding](https://docs.pingidentity.com/sdks/latest/sdks/use-cases/how-to-bind-devices.html). ## Example The following example shows a device binding journey that registers a device to the user, checks the collected device data meets certain criteria, and stores the device data in the user's profile: ![Device binding journey example](_images/device-binding-journey.png) * The [Page node](page.html) containing the [Platform Username node](platform-username.html) and [Platform Password node](platform-password.html) prompts for credentials. * The [Data Store Decision node](data-store-decision.html) validates the username-password credentials. * The [Device Binding node](device-binding.html) is configured with the Store Device Data in Transient State option enabled. The node initiates the binding process on the user's device. When the user completes the process, the node stores the collected device data in the transient state. * The [Scripted Decision node](scripted-decision.html) inspects the device data before it's saved. For example, you could use this node to enforce a policy that only allows devices with certain characteristics to be registered. If the device doesn't meet the policy, the script can route the journey to the `Failure` outcome path, preventing the device data from being saved. * The [Device Binding Storage node](device-binding-storage.html) retrieves the device data from the transient state and saves it to the user's profile in the identity store. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you don't need to do anything with the device data before it's saved, you can configure the [Device Binding node](#store-device-data-setting) to store the device data in the user's profile. This would simplify the journey because the [Device Binding Storage node](device-binding-storage.html) wouldn't be needed. | ## 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 [Platform Username node](platform-username.html) earlier in the journey. ## Dependencies To use Android Key Attestation, you must also configure the [Android Key Attestation Service](https://docs.pingidentity.com/pingoneaic/am-reference/services-configuration.html#realm-androidkeyattestation). ## Configuration | Property | Usage | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication Type | 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 device PIN if biometric is unavailable. - `Application PIN` Request that the client secures access to the cryptography keys with an application-specific PIN. The application-specific PIN applies only to your app, and isn't linked to the device PIN used to unlock the device. The application-specific PIN is stored only on the client device and isn't sent to Advanced Identity Cloud. If the user forgets their application-specific PIN, they must bind the device again. - `None` The user doesn't need to authenticate to gain access to the private keys on their device. | | Application IDs | The Android package names and iOS bundle IDs of applications that are allowed to perform device binding.For example, `com.example.app`. | | Title | (Optional) Add a title to display to the user when asking them to bind the device.> **Collapse: Add instructions** > > 1. Click [icon: plus, set=fa]. > > 2. In the Key field, enter the locale. For example, `en-gb`.[(1)](#locale-footnote) > > 3. In the Value field, enter the message. > > 4. Click Done. > > 5. Repeat to add more messages and save your changes when you're done.Leave blank to use the default message. | | Subtitle | (Optional) Add a subtitle to display to the user when asking them to bind the device.> **Collapse: Add instructions** > > 1. Click [icon: plus, set=fa]. > > 2. In the Key field, enter the locale. For example, `en-gb`.[(1)](#locale-footnote) > > 3. In the Value field, enter the message. > > 4. Click Done. > > 5. Repeat to add more messages and save your changes when you're done.Leave blank to use the default message. | | Description | (Optional) Add descriptive text to display to the user when asking them to bind the device.> **Collapse: Add instructions** > > 1. Click [icon: plus, set=fa]. > > 2. In the Key field, enter the locale. For example, `en-gb`.[(1)](#locale-footnote) > > 3. In the Value field, enter the message. > > 4. Click Done. > > 5. Repeat to add more messages and save your changes when you're done.Leave blank to use the default message. | | Maximum Saved Devices | The maximum number of devices stored in the user's profile.Set this property to `0` if you don't want to limit the number of devices.When this property is greater than zero, the `Exceed Device Limit` outcome path becomes available. | | Timeout | 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 | Select this option to 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 transient state, in a variable named `DeviceBindingCallback.ATTESTATION`, so that you can access and parse the data in a scripted node if required.You can find information on the contents of the attestation data JSON response in [Attestation certificate](https://source.android.com/docs/security/features/keystore/attestation#attestation-certificate) in the Android documentation. | | []()Store Device Data in Transient State | Select this option to store device data in transient state instead of the user's profile.When enabled, device information is added to a variable named `DeviceBinding.DEVICE` in transient state. This allows subsequent nodes to use, parse, or alter the information before saving it. Use the [Device Binding Storage node](device-binding-storage.html) to save the device data to the user's profile.If you don't set this option, the node saves device data in the user's profile.> **Collapse: Example device data** > > ```json > { > "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" > } > } > ``` | | Client Error Outcomes | The client error outcomes available to this node. Find more information in [Error handling](https://docs.pingidentity.com/sdks/latest/sdks/use-cases/how-to-bind-devices.html#error_handling). | | Skew Allowance | The maximum allowed time difference in seconds (clock skew) between the client device and Advanced Identity Cloud. This helps prevent binding failures caused by clocks being out of sync.Default: `60` seconds | (1) Specify a [locale that Java supports](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Locale.html), such as `en-gb`. Otherwise, the node throws a configuration exception with an `Invalid locale provided` message. ### 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, haven't been revoked, and use hardware-backed security storage. The Ping 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 *isn't* supported if you select `Application PIN` in the Authentication Type property. Evaluation continues down the `Unsupported` outcome path in this case. The node doesn't attempt attestation when binding non-Android devices. ## Outputs * If you enable the Android Key Attestation property, the node outputs attestation data to the `DeviceBindingCallback.ATTESTATION` variable in transient state. * If you enable the Store Device Data in Transient State property, the node outputs device data to the `DeviceBinding.DEVICE` variable in transient state. ## Callbacks The node sends a [DeviceBindingCallback](https://docs.pingidentity.com/pingoneaic/am-authentication/callbacks-interactive.html#DeviceBindingCallback) to the user's device to initiate the device binding process. ## Outcomes * `Success` The user successfully binds their device. * `Failure` An issue occurred during the binding process. * `Exceed Device Limit` 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. In this case, you need to instruct your users to log in with an existing bound device to remove one or more of their registered devices. * `Unsupported` This outcome is available only if listed in the Client Error Outcomes property. The user's client doesn't support the requested operation. For example, the node is configured to require biometric authentication, but the device doesn't provide support. * `Abort` This outcome is available only if listed in the Client Error Outcomes property. The user cancels the attempt to bind a device. * `Timeout` This outcome is available only if listed in the Client Error Outcomes property. The node doesn't receive a response from the user's device within the Timeout specified in the node configuration. ## Errors The node can log the following errors: * `An error occurred while retrieving user's device` The node can't retrieve all the user's bound devices so is unable to check whether they've exceeded the maximum saved devices limit. This error can only occur if the Maximum Saved Devices property is set to an integer greater than zero. The node can log the following warnings: * `Device Binding failed` The node failed to bind the device. This can occur for a variety of reasons, such as the client device not being able to access the cryptography keys for binding. * `Username attribute not found` The node can't retrieve the `username` attribute from the user's identity.