PingOne Platform APIs

Remembered Devices

To reduce the friction of frequent authentication requests, your MFA policies can allow the use of a "remember me" option. When you enable this option, you specify the maximum time a device can be remembered. During this period, if a user tries to access applications from the same computer and browser, they will not be asked for further authentication.

The use of this feature requires the following elements:

  • Embedding the Signals SDK in the UI of your application.

  • Adding a "remember me" option to the UI of your application.

  • Enabling the "remember me" option in the MFA policies that you plan on using.

  • Sending an API request with the relevant information so that the user’s browser is recorded as a remembered device.

  • When the user subsequently tries to access an application, sending the API request that compares the current browser information with the information that was recorded previously.

To use the remembered device mechanism, the Signals SDK must have the universalDeviceIdentification option enabled. If the option is not enabled, you will get an error regarding the SDK payload when you try to create the remembered device.

Creating a remembered device

To create a remembered device:

  1. Get the ID of the MFA policy that is being used.

  2. Get the details of the MFA policy.

  3. Check the content of the rememberMe object in the MFA policy to see if the "remember me" option can be used with this policy (rememberMe.web.enabled).

  4. If "remember me" is enabled, send a request using the devices endpoint, as shown in the Create Remember Me Device example.

  5. The response to the request will include a cookie in the set-cookie header. When it comes time to check if a device is remembered, you will have to include this cookie in the headers for the request.

Checking if device is recognized

To check if a user is using a remembered device:

  1. Get the ID of the MFA policy that is being used.

  2. Get the details of the MFA policy.

  3. Check the content of the rememberMe object in the MFA policy to see if the "remember me" option can be used with this policy (ememberMe.web.enabled).

  4. If "remember me" is enabled, send a request using the deviceAuthentications endpoint and the application/vnd.pingidentity.payload.check+json header, as shown in the Check if Device Remembered example. The headers must also include the cookie that was returned when the remembered device was created. Note that if you included the PingOne session ID by using the optional session.id parameter when creating the remembered device, you must include the deviceSession.id parameter when checking if the device is remembered.

Create Remembered Device data model

Property Type Required? Mutable? Description

cookiesEnabled

Boolean

N/A

Read-only

Whether cookies are enabled for the browser.

createdAt

Date

N/A

Read-only

The date and time the remembered device was created.

environment.id

String

N/A

Read-only

The ID of the PingOne environment.

id

String

N/A

Read-only

The ID of the remembered device.

jsFingerprint

String

N/A

Read-only

The fingerprint of the browser.

lastAuthenticationMethod

String

Optional

Immutable

To cover situations where certain applications require a more secure authentication method, you can use this field to provide the authentication method that was used when the remembered device was created. In subsequent access requests, when PingOne checks if a remembered device is being used, it will also verify that the method used during creation is an allowed authentication method for the current MFA policy. If the method used during creation is not allowed by the current MFA policy, the status FAILED is returned. The response to the deviceAuthentications request that completed the authentication process can be used to identify the authentication method that was used: The value of selectedDevice.id is the ID of the device that was used, and the _embedded.devices array contains the details of the user’s paired devices, including ID and device type.

lastRememberedAt

Date

N/A

Read-only

The date and time that the create remember me request was last sent for this device.

locale

String

N/A

Read-only

The locale set on the device.

name

String

N/A

Read-only

The name of the browser.

nickname

String

N/A

Read-only

The browser nickname.

operatingSystem.name

String

N/A

Read-only

The operating system installed on the device.

operatingSystem.version

String

N/A

Read-only

The version of the operating system installed on the device.

payload

String

Required

Mutable

The payload from the Signals SDK .

policy.id

String

Required

Mutable

The ID of the relevant MFA policy. For creating a remembered device, you must use an MFA policy that has been enabled for the "remember me" feature.

pushNotificationSupport

Boolean

N/A

Read-only

Whether push notifications are enabled for the browser.

screenResolution.height

Integer

N/A

Read-only

The screen resolution height.

screenResolution.width

Integer

N/A

Read-only

The screen resolution width.

session.id

String

Optional

Mutable

For an added layer of security, you can also include the ID for a user’s PingOne session. This parameter is optional, however, if you include it when creating the remembered device, you must also include the session ID (deviceSession.id) when you try checking if the device is remembered.

status

String

N/A

Read-only

The status of the device, for example, ACTIVE.

type

String

Required

Immutable

Must be set to BROWSER.

updatedAt

Date

N/A

Read-only

The date and time the remembered device was last updated.

userAgent

String

N/A

Read-only

User agent string for the browser.

version

String

N/A

Read-only

The version of the browser.

Check Remembered Device data model

Property Type Required? Mutable? Description

authenticators

Array

N/A

Read-only

Included in response when checking if device is a remembered device. If the device was recognized as a remembered device, the array will contain the values rm, mfa, and swk.

bypassAllowed

Boolean

N/A

Read-only

Indicates whether the authentication policy allows users to bypass MFA if they do not have a compatible authentication method.

createdAt

Date

N/A

Read-only

The date and time the remembered device was created.

deviceSession.id

String

Optional

Mutable

If you included the ID for a PingOne user session when creating the remembered device, you must also include the session ID when checking if the device is a remembered device. When creating the remembered device the parameter to use is session.id. When checking if the device is a remembered device, the parameter to use is deviceSession.id.

environment.id

String

N/A

Read-only

The ID of the PingOne environment.

id

String

N/A

Read-only

The ID of the flow.

payload.type

String

Required

Immutable

Value must be set to BROWSER.

payload.value

String

Required

Mutable

The payload from the Signals SDK.

policy.id

String

Required

Mutable

The ID of the relevant MFA policy.

selectedDevice.id

String

N/A

Read-only

The ID of the remembered device.

status

String

N/A

Read-only

The status of the check - COMPLETED if the device was recognized as a remembered device, FAILED if not.

updatedAt

Date

N/A

Read-only

The date and time the remembered device was last updated.

user.id

String

Required

Mutable

The ID of the user. Required when checking if the device is a remembered device.

userBypassEnabled

Boolean

N/A

Read-only

Indication of whether the specific user is currently permitted to bypass MFA.

_embedded.blockedDevices

Array

N/A

Read-only

Lists any of the users’s authentication methods that are currently blocked.

_embedded.devices

Array

N/A

Read-only

Information on all of the authentication methods registered for the user.