PingAM 8.0.1

Reset registered devices over REST

As described in Recover after replacing a lost device, a user who has lost a mobile phone registered with AM can register a replacement device by authenticating using a recovery code, deleting their existing device, and then registering a new device.

Additional support is required for users who lose mobile devices but did not save their recovery codes when they initially registered the device, and for users who have used up all their recovery codes.

AM provides a REST API to reset a device profile by deleting information about a user’s registered device. Both the user and administrator accounts can use the REST API to reset a device profile. Administrators can:

  • Provide authenticated users with a self-service page that calls the REST API to reset their devices.

  • Call the REST API themselves to reset a user’s device profiles.

  • Call the REST API themselves to reset a device that is out of sync, where the HOTP counter exceeds the HOTP threshold window and requires a reset.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/customers/realms/europe.

Reset OATH devices

To reset a user’s OATH device profile, send an HTTP POST request to the /users/user/devices/2fa/oath?_action=reset endpoint.

The following example resets the OATH devices of a user named myUser in a realm called alpha:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
--data '{}' \
'/json/realms/root/realms/alpha/users/myUser/devices/2fa/oath?_action=reset'
{
    "result":true
}
bash

The reset action deletes the OATH device profile, which by default has a limit of one profile per device, and sets the Select to Enable Skip option to its default value of Not Set.

Reset push devices

To reset push devices over REST, send an HTTP POST request to the /users/user/devices/2fa/push?_action=reset endpoint.

The following example resets push devices for a user named myUser in a realm called alpha:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
--data '{}' \
'/json/realms/root/realms/alpha/users/myUser/devices/2fa/push?_action=reset'
{
    "result":true
}
bash

Delete WebAuthn devices

The reset action is not implemented on the webauthn endpoint.

You can delete a WebAuthn device over REST as follows:

  1. Retrieve a list of WebAuthn devices associated with a user by querying the users/user/devices/2fa/webauthn endpoint.

    The following example retrieves a list of WebAuthn devices for a user named myUser in a realm called alpha:

    $ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
'/json/realms/root/realms/alpha/users/myUser/devices/2fa/webauthn?_queryFilter=true'
{
  "result": [
    {
      "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "_rev": "163664231",
      "deviceName": "New Security Key",
      "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
      "deviceManagementStatus": false
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
    bash

  2. Delete the required WebAuthn device from the user by sending an HTTP DELETE request to the users/user/devices/2fa/webauthn/device-id endpoint, including the ID of the WebAuthn device you want to delete:

    $ curl \
--request DELETE \
--header "Accept-API-Version: resource=1.0" \
--header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
'/json/realms/root/realms/alpha/users/myUser/devices/2fa/webauthn/ff1db8bf-d2d7-46e1-926a-568b877f87a5'
{
  "_id": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
  "_rev": "1642022518",
  "uuid": "ff1db8bf-d2d7-46e1-926a-568b877f87a5",
  "recoveryCodes": [
    ...
  ],
  "credentialId": "XGJpYNYv4AHG9sHHgxFfTw",
  "algorithm": "SHA256withECDSA",
  "deviceName": "New Security Key",
  "key": {
    "kty": "EC",
    "x": "zMDAfFwRQR_5HIGfK1iJQ0kYwtudesx_UXocoBVrWbo",
    "y": "UgRBOBlpq6QYsXlqfHDzY8XNv-5DEMajRp9_3klkhDU",
    "crv": "P-256"
  }
}
    bash

  3. Repeat step 2 to delete additional WebAuthn devices for the user, if needed.

Reset bound devices

To delete all bound devices for a user, send an HTTP POST request to the /users/user/devices/2fa/binding?_action=reset endpoint. Learn more about binding devices to a user profile in device binding.

The following example deletes bound devices for a user named myUser in a realm called alpha:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "iPlanetDirectoryPro: AQIC5w…​2NzEz*" \
--data '{}' \
'/json/realms/root/realms/alpha/users/myUser/devices/2fa/binding?_action=reset'
{
    "result":true
}
bash

Deleting a bound device on the server does not remove the private keys from the device.

Instead, you can use the Ping SDKs to remove the bound device from the server, and then remove the keys from the device. Refer to Unbind devices by deleting keys.

Refresh push device IDs

The Push Notification service relies on device tokens or IDs issued by the Android and iOS platforms to deliver notifications to end users. These platforms occasionally issue new device tokens. Depending on the platform, there are several reasons a device ID might change:  

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.

To make sure push notifications are received correctly, the Push Notification service must have the most recent device ID for a particular device.

When a new device ID is issued on a device, the following steps must occur:

  1. The Ping SDKs send an HTTP POST request to the /json/realms/realm-name/push/sns/message endpoint with action=refresh.

    The request includes the mechanismUid, username, and a JWT that includes the new deviceID.

  2. The Push Notification service decodes the JWT and extracts the new deviceID.

  3. The Push Notification service locates the user’s push device profile, based on the username, and updates the value of the deviceID.

If you’re not using the Ping SDKs, you must adapt your authenticator application to follow these steps.