Device self-service in JavaScript apps

PingOne Advanced Identity Cloud PingAM JavaScript

The Device Client module for JavaScript provides a comprehensive and unified API for managing Multi-Factor Authentication (MFA) devices and user profile devices registered with Advanced Identity Cloud or PingAM servers.

The module simplifies the process of retrieving, updating, and deleting various types of authentication devices, enabling you to build secure and user-friendly device management experiences within your JavaScript applications.

Installing modules

The Device Client client module for JavaScript as available as an npm module at @forgerock/device-client.

To install the module into your JavaScript project, run the following npm command:

npm install @forgerock/device-client@2.0.0

After installation, import the deviceClient module and ConfigOptions type into your app as follows:

import { deviceClient } from '@forgerock/device-client';
import type { ConfigOptions } from '@forgerock/device-client/types';

Initializing the device client

The Device Client module uses the REST-based device management endpoints provided by Advanced Identity Cloud and PingAM.

The Device Client module requires the session token when making calls to the device management endpoints. In a JavaScript app, the session cookie is automatically attached to outgoing calls to the REST API.

Session tokens often have a short duration and might expire after 5 minutes. If the client does not have an active session token you should trigger an authentication journey to obtain a new session token before attempting to manage registered devices.

The following code shows how to initialize the device client module after authenticating a user and obtaining their session token:

Initializing a device client on JavaScript

const config: ConfigOptions = {
  serverConfig: {
    baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
  },
  realmPath: 'alpha',
};

const deviceClient = deviceClient(config);

The configuration properties for the device client are as follows:

Device client parameters on JavaScript
Parameter	Description	Required?
`serverConfig/baseUrl` (String)	The base URL of your server. Advanced Identity Cloud example `https://openam-forgerock-sdks.forgeblocks.com/am` PingAM example `https://openam.example.com:8443/openam`	Yes
`realmPath` (String)	The authentication realm. Advanced Identity Cloud example `alpha` PingAM example `root`	Yes

Listing registered devices

For each type of registered device you can call the devices() method to retrieve a list from the server. Pass the ID of the user whose device you want to list in the userId parameter, and the realm in the realm parameter.

Advanced Identity Cloud example

{
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha'
}

Advanced Identity Cloud references users by their _id value.

You can get this ID from the raw JSON for the user’s profile.

PingAM example

{
  userId: 'demo',
  realm: 'root'
}

The available types of device are as follows:

Getting lists of registered devices by type on JavaScript
Registered device type	Listing method
WebAuthn / FIDO authenticators	`deviceClient.webAuthn.get()`
Bound devices	`deviceClient.bound.get()`
Profiled devices	`deviceClient.profile.get()`
Push MFA devices	`deviceClient.push.get()`
OATH MFA devices	`deviceClient.oath.get()`

Each method returns a promise for improved error handling and functional programming support.

The different device types return different relevant information that you can access and display to the user as appropriate, such as the current name or when the device was last used.

The following code shows how to obtain lists of the different devices from the server:

WebAuthn / FIDO
Bound devices
Profiled devices
Push devices
OATH devices

Listing WebAuthn devices on JavaScript

const webAuthnQuery: WebAuthnQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.webAuthn.get(webAuthnQuery);
console.log('WebAuthn Devices:', devices);

Listing bound devices on JavaScript

const bindingQuery: GetBoundDevicesQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.bound.get(bindingQuery);
console.log('Bound Devices:', devices);

Listing Profiled devices on JavaScript

const profileQuery: GetProfileDevices = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.profile.get(profileQuery);
console.log('Device Profiles:', devices);

Listing Push devices on JavaScript

const pushQuery: PushDeviceQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.push.get(pushQuery);
console.log('Push Devices:', devices);

Listing OATH devices on JavaScript

const oathQuery: RetrieveOathQuery = {
  userId: '014c54bd-6078-4639-8316-ch15e7746fa4',
  realm: 'alpha',
};

const devices = await apiClient.oath.get(oathQuery);
console.log('Oath Devices:', devices);

Renaming devices

You can rename registered devices and update the user’s account with the new details by using the update() method.

You’ll need to identify the device to update by using the device query parameter. You can obtain an array of device objects from the call to get() earlier.

You also need to specify the owner of the device in the userId parameter, and the realm in the realm parameter. The Device Client module uses these parameters to form the REST endpoint it uses for device management.

For example, the following code renames a registered bound device that has the UUID ee19db01-7c1a-41b3-971b-646341189d42:

Renaming a bound device on JavaScript

const updateBoundQuery = {
  userId: 'ee19db01-7c1a-41b3-971b-646341189d42',
  realm: 'alpha',
};

const updatedDevice = await apiClient.bound.update({
  ...updateBoundQuery,
  device: { ...device, deviceName: 'My Updated Device Name' },
});

if ('error' in updatedDevice) {
  console.error(`Failed to update device: ${updatedDevice.error}`);
}

console.log('Updated bound device', updatedDevice);

All update operations automatically include an If-Match: * HTTP header.

This header is used for optimistic concurrency control to prevent conflicts when multiple clients attempt to modify the same device simultaneously.

The wildcard * value allows updates regardless of the current ETag, ensuring the update succeeds if the resource exists.

Deleting devices

You can delete or deregister a device, with the caveat that the authentication journey that provided the users' session must fulfill one or more of the following criteria:

Used same multi-factor authentication method as the device you want to delete.

For example, to delete a WebAuthn device the authentication journey that created the session must also authenticate using a WebAuthn device.
Used the Enable Device Management node that alters the Device Check Enforcement Strategy.

Use the delete() method to delete a device from the user’s profile.