The multi-factor authentication settings (MFA) control whether a user can authenticate using MFA actions. This endpoint enables or disables MFA capability.

For information about user MFA device management, refer to MFA devices.

MFA settings data model

Response codes

You can use the bypassMFA endpoint to define a period during which a specific user should be allowed to bypass MFA. You can also use the endpoint to check whether a specific user is currently permitted to bypass MFA.

To enable multi-factor authentication (MFA), the user resource must have an MFA method associated with its user ID. PingOne supports email, SMS, voice, TOTP authenticator application, and native application method types for use in an MFA flow. Multiple MFA methods can be associated with a user ID. MFA methods must be in the active state to be used in the multi-factor login flow.

With this API, MFA methods are called MFA devices. The devices endpoints provide operations to manage device resources associated with a specified user ID. You need the Identity Data Admin role to perform operations on device resources.

Device order

With the release of the device order feature (Jan 11, 2021), the active devices of most users now have an order (first...last). By default, the order is according to the device activation time (oldest...newest). Each subsequently activated device is appended to the end of the order list. The first device on the list is designated the default device. In most cases, the default device is automatically used for authentication; users no longer need to select a device.

There are a small number of users whose devices do not have a default order with this feature. If a user has more than one active device as of the release of the device order feature, the current active devices and subsequently activated devices have no order. The user therefore has no default device and must choose a device each time they authenticate. In this case, the order must be explicitly set (refer to Setting device order).

Cases where the default device is not used for authentication

In most cases, the default device is automatically used for authentication. However, there are two exceptions:

• If authenticating from a native app and device authorization is enabled, the native device is used for seamless authentication (see Automatic device authorization under PingOne MFA Native SDK Flows).
• If the user is paired with a FIDO2 platform device and a session token cookie exists on the browser, the FIDO2 platform device is used for authentication even if it is not the default device.

Setting device order

The operation POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.reorder+json explicitly orders a user's existing active devices according to the request body. The active device listed first becomes the default device.

After this operation explicitly sets device order, subsequently activated devices are appended to the end of the order list. You can use this operation to explicitly reorder active devices as many times as needed.

Retrieving an ordered list of devices

The operation GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices returns the list of active devices sorted in their order, with the default device listed first. Devices with a status of ACTIVATION_REQUIRED are listed after the active devices, in no particular order. If devices have no order, GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices returns the list of devices in no particular order.

You can expand the GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results with the expand=order query parameter. The response is then expanded to contain an array of activated device IDs listed according to device order. If devices have no order, an empty array is returned.

Deleting a default device

If the default (first) device is deleted, the second active device on the order list becomes the default device.

Removing device order

The operation POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices with required header Content-type: application/vnd.pingidentity.devices.order.remove+json removes the ordering on a user's active devices. With the execution of this operation, the user no longer has a default device.

Custom device pairing notification with device creation

To send a custom device pairing notification when a new email, SMS or voice device is created, add the notification property to the request body of POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices. The status of the created device must be ACTIVATION_REQUIRED.

{
    "notification": {
        "template": {
            "locale": "en",
            "variant": "variant_B"
            "variables": {
                        "sum": "1,000,000",
                        "currency": "USD",
                        "recipient": "Charlie Parker"
            }
       }
    }
}

When the device is created, a request is executed to select the content for the notification. The notification template is device_pairing. The deliveryMethod is Email, SMS or Voice, depending on the device created. The locale, variant, and all dynamic variables are defined in notification.

For more information on content selection, refer to Runtime logic for content selection. For more information on dynamic varables, refer to Dynamic variables.

Device failure in flows

When the flow returns a NO_USABLE_DEVICES error, and the user has devices that are temporarily unavailable (for example, the device is locked because of too many invalid OTP retries), the IDs of these devices are returned as part of the response.

In the flow response, the status property returns FAILED, and the error message includes the NO_USABLE_DEVICES error code. The following samples show common error messages for a device failure with identified unavailableDevices:

"status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Couldn't find authenticating device for user: {{userID}}",
      "unavailableDevices": [
            {
                "id": "edccc773-6f31-4d28-a8e1-0f427d9a9df8"
            }
        ]
    },

"status": "FAILED",
    "error": {
        "code": "NO_USABLE_DEVICES",
        "message": "Daily limit of SMS authentication attempts has been exceeded",
        "unavailableDevices": [
            {
                "id": "7ea99e29-6f8f-42be-af75-232588235e30"
            }
        ]
    },

Device properties

EMAIL device properties

Devices whose type is EMAIL also have the following properties:

SMS/Voice device properties

Devices whose type is SMS or VOICE also have the following properties:

Native device properties

Devices whose type is MOBILE also have the following properties:

Time-based One-time Password (TOTP) authenticator application device properties

Devices whose type is TOTP also have the following properties:

FIDO2 devices

Devices whose type is FIDO2 also have the following properties:

OATH token devices

OATH tokens can be used only in PingOne environments where a PingID account has been integrated.

Devices whose type is OATH_TOKEN also have the following properties:

PLATFORM and SECURITY_KEY webauthn device data model (deprecated, replaced by FIDO2 devices)

Devices whose type is PLATFORM or SECURITY_KEY also have the following properties:

Device order properties

MFA devices events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Filtering result data

You can filter GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set.

SCIM operators can be applied to the following attributes:

The logical operators and and or can also be used to combine filter statements.

For example, the following URL-encoded SCIM filter returns a list of SMS devices that require activation:

{{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=(status%20eq%20%22ACTIVATION_REQUIRED%22)%20and%20(type%20eq%20%22SMS%22)

This URL returns the device that matches the information contained in the specified payload from the PingOne Mobile SDK:

{{apiPath}}/environments/{{envID}}/users/{{userID}}/devices?filter=mobilePayload eq "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz..."

Expanding result data

You can expand GET {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices results with the expand=<value> query parameter. The following value is supported.

Related topics

To enable multi-factor authentication (MFA) via push notification on a native device, the user resource must have a native device and an application associated with its user ID. The association is implemented with a pairing key.

The pairing key endpoints provide operations to create, read, and remove pairing key resources associated with a specified user ID, native device and application. The examples below show common actions to manage pairing keys.

Creating a native device with a pairing key

A user cannot create a native (mobile) device with POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/devices. The user must create the device with a pairing key:

1. The user installs a native app with an embedded PingOne MFA Native SDK component.

2. The user starts an MFA authentication flow and creates a pairing key. Refer to Multi-factor MFA Action in the Developer Guide for more information.

3. The user scans the pairing key QR code with the native app.

4. The embedded PingOne MFA Native SDK starts the pairing process where the device resource is created. Refer to PingOne MFA SDK for Android or PingOne SDK for iOS.

Pairing key data model

Response codes

The /deviceAuthentications endpoint initiates and completes an MFA action without requiring a call to the PingOne authorize service. It supports actions to select a supported MFA device device type and to validate a one-time passcode (OTP).

When a device authentication MFA flow is initiated, the flow returns a status property in the response that identifies the next action in the flow. The following flow states prompt for a specific flow action:

• OTP_REQUIRED

  For a status value of OTP_REQUIRED, the otp.check action validates the one-time passcode.

• DEVICE_SELECTION_REQUIRED

  For a status value of DEVICE_SELECTION_REQUIRED, the device.select action prompts the user to select a supported device type for use in a multi-factor authentication flow.

• ASSERTION_REQUIRED

  For a status value of ASSERTION_REQUIRED, the assertion.check action validates the assertion.

• PUSH_CONFIRMATION_REQUIRED

  For a status value of PUSH_CONFIRMATION_REQUIRED, a push was sent to the specified mobile device to confirm the authentication.

• PUSH_CONFIRMATION_TIMED_OUT

  For a status value of PUSH_CONFIRMATION_TIMED_OUT, a push was sent to the specified mobile device, but the mobile device did not answer the push during the allowed timeframe.

Device authentications data model

Device authentication events generated

Refer to Audit Reporting Events for the events generated.

The /authenticationCodes endpoint provides operations to create, read, and delete an authentication code. The authentication code (which can be a QR code) enables users to sign on without any data entry, such as providing a username, password, or entering a one-time passcode. The user scans the code, and if successful, gains access to an application's services.

Authentication codes request data model

Authentication codes response data model

For descriptions of other fields under _embedded.device, refer to MFA Devices.

For descriptions of fields under _embedded.user, refer to Users data model.

Device authentication policies (identified in the PingOne UI as "MFA Policies") enable you to configure different settings per MFA authentication method, according to your security policies.

Device authentication policy data model

"fido2" : {
    "enabled" : true,
    "pairingDisabled" : false
}

"mobile": {
    "enabled": true,
    "otp": {
        "failure": {
            "count": 3,
            "coolDown": {
                "duration": 2,
                "timeUnit": "MINUTES"
            }
        }
    },
    "applications": [
        {
            "id": "{{appID}}",
            "push": {
                "enabled": true,
                "numberMatching": {
                    "enabled": true
                }
            },
            "otp": {
                "enabled": true
            },
            "pushTimeout": {
                "duration" : 120,
                "timeUnit" : "SECONDS"
            },
            "pushLimit": {
                "count": 4,
                "timePeriod": {
                    "duration": 10,
                    "timeUnit": "MINUTES"
                },
                "lockDuration": {
                    "duration": 30,
                    "timeUnit": "MINUTES"
                }
            },
            "deviceAuthorization": {
                "enabled": true,
                "extraVerification": "permissive"
            },
            "autoEnrollment": {
                "enabled": true
            },
            "pairingKeyLifetime": {
                "duration": 40,
                "timeUnit": "HOURS"
            },
            "integrityDetection": "permissive"
        }
    ]
}

This table includes the properties that are used for the PingID mobile app. All of the fields in the table below should be enclosed in the mobile object, as in the example in Mobile device authentication policy data model.

Refer to Audit Reporting Events for the events generated.

Related topics

You can use the reporting capability to generate reports containing user and MFA device details, using a number of device-related filters.

For example, you can generate a report listing all email devices or a report containing all of the devices whose phone number starts with a certain country code.

You can use synchronous requests to get back the matching data as entries in the JSON response or use asynchronous requests to have the data provided in a CSV or JSON file. Note that when using the synchronous approach, you may have to make multiple requests if there is a large amount of data.

The request for generating reports uses the dataExplorations endpoint:

https://{{apiPath}}/v1/environments/{{envId}}/dataExplorations

MFA reports data model

Getting the report results

You can receive the report data as entries in the JSON response or as a file (CSV or JSON).

There are a number of ways you can get the report results. The recommended approaches for the most common scenarios are as follows:

• For cases where you anticipate a fairly small number of records in the results:

  • Run a POST request using the expand query parameter. This will create the dataExplorations object and also return the results as entries in the response. {{apiPath}}/environments/{{envID}}/dataExplorations?expand=entries

    For more information on the use of the expand query parameter, see "Link expansion" under Conventions.

• For cases where you expect a large number of records, but would like to receive them as entries in the body of the response:

  1. Run a POST request to create the dataExplorations object.

  2. Run a GET request with /entries in the URL: {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}}/entries

  3. If there are too many results to include in one response, the _links section in the response will include a next object. Follow the next link, then using the same access token, run another GET request using the the next link as the URL.

  4. Continue until the response no longer includes a next object.

     For more information on pagination, refer to Paging, ordering, and filtering collections.

• For cases where you want to receive the results as a file:

  1. Run the request to create a report and get the results as a file: POST {{apiPath}}/environments/{{envID}}/dataExplorations. In the body of the request, make sure that deliverAs is set to ASYNC_FILE.
  2. The response to the report creation request will include a status field whose value is IN_PROGRESS.
  3. Run the polling request GET {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}}, using the ID that was returned when you created the report, until the status field in the response equals SUCCESS.
  4. When the response contains the status SUCCESS, it will also include a link for downloading a zipped csv file, a link for downloading a zipped JSON file, and a password for opening the zip files. Use this information to download and unzip the report.
  5. The report itself is cached for two hours, but the links are good for only five minutes.
  6. If more than five minutes has elapsed from the time of the request that returned the links, get updated links by again running the request GET {{apiPath}}/environments/{{envID}}/dataExplorations/{{dataExplorationID}} using the ID that was returned when you created the report.
  7. If more than two hours has elapsed since the report was created, run the report creation request again.

The MFA settings endpoint supports operations to read, update, and reset the PingOne MFA settings associated with a specified environment. A PUT request lets you manage the maximum number of allowed devices for pairing, and it lets you set the device selection option. A successful DELETE operation resets the MFA settings to the default.

Maximum allowed devices

The MFA settings property pairing.maxAllowedDevices defines the maximum number of paired MFA devices each user within an environment can have. This can be any number up to 15. The default value is 5. You can update the setting with GET {{apiPath}}/environments/{{envID}}/mfaSettings and reset the setting to its default with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

If the maxAllowedDevices value is decreased below the number of paired devices a user currently has, the user's existing paired devices remain. After a paired device is deleted though, the user cannot replace it with a new one. This remains true until the number of existing paired devices is below the current value for maxAllowedDevices.

If the maxAllowedDevices limit is reached and the user attempts to create a new device, an error similar to the following is returned.

400 BAD REQUEST
{
  "id": "<errorId>",
  "code": "REQUEST_FAILED",
  "message": "The request could not be completed. There was an issue processing the request.",
  "details": [
    {
      "code": "LIMIT_EXCEEDED",
      "message": "Maximum allowed devices has been reached",
      "innerError": {
        "maximumAllowed": 5
      }
    }
  ]
}

Account lockout

The MFA settings property lockout.failureCount and lockout.durationSeconds defines the maximum number of incorrect MFA authorization actions a user can attempt (such as entering an incorrect OTP or denying a push confirmation on a native device) before the account is locked. The lockout.durationSeconds defines the amount of time after the lockout.failureCount value is exceeded to keep the account in a locked state. You can update the setting with PUT {{apiPath}}/environments/{{envID}}/mfaSettings.

For more information about account lockout, refer to User Accounts.

MFA settings data model

Response codes

You can use the PingOne API for various oath token management actions, including creating tokens, revoking tokens, and resyncing tokens.

FIDO policies allow you to fine-tune the use of FIDO2 authentication in authentication flows, for example, by limiting authentication to specific types of FIDO2 devices.

An endpoint (fidoDevicesMetadata) is also provided for reading information from the device metadata table stored by PingOne, and for adding or removing custom devices.

FIDO policies data model

Additional information returned in responses

• id - the ID assigned to the policy
• createdAt
• updatedAt
• _embedded.deviceAuthenticationPolicies - array of the device authentication polices that the FIDO policy is used by. Each object in the array consists of the ID of the device authentication policy and the name of the device authentication policy. Returned only if the query includes the parameter expand=deviceAuthenticationPolicies.

FIDO policies events generated

Refer to Audit Reporting Events for the events generated.

FIDO device metadata

PingOne maintains a global authenticator table, which presents metadata for indvidual authenticators. This includes both authenticators that are represented in the FIDO Alliance Metadata Service (MDS), and custom authenticator data that you add to the table via the UI or the API.

The endpoints provided for FIDO device metadata allow you to:

• Retrieve the basic metadata for all of the authenticators in the table
• Retrieve detailed metadata for a specific authenticator from the table
• Add metadata for custom authenticators
• Delete from the table a custom authenticator that you added

Adding a custom authenticator

When you use the fidoDevicesMetadata endpoint to add a custom authenticator to the global authenticator table, the data included in the request should comform with the Metadata Statement Format provided by the FIDO Alliance.

Before adding an authenticator, using JSON data provided by a manufacturer, verify that it conforms to the following details expected by the PingOne API:

• The metadata outlined in the standard should be enclosed in an object called metadataStatement.
• The metadataStatement should be enclosed in an object that also includes the relevant key identifier: the attestationCertificateKeyIdentifiers array for devices conforming with the U2F protocol, and the aaguid field for devices conforming with the FIDO2 protocol.

Sample body for request - U2F device

{
    "attestationCertificateKeyIdentifiers": [
        "31116a647069d1493f58fc5b54e5449e2a52d43e"
    ],
    "metadataStatement": {
        "legalHeader": "https://fidoalliance.org/metadata/metadata-statement-legal-header/",
        "attestationCertificateKeyIdentifiers": [
            "31116a647069d1493f58fc5b54e5449e2a52d43e"
        ],
        "description": "Yubikey Edge",
        "authenticatorVersion": 1,
        "protocolFamily": "u2f",
        "schema": 3,
        "upv": [
            {
                "major": 1,
                "minor": 1
            }
        ],
        "authenticationAlgorithms": [
            "secp256r1_ecdsa_sha256_raw"
        ],
        "publicKeyAlgAndEncodings": [
            "ecc_x962_raw"
        ],
        "attestationTypes": [
            "basic_full"
        ],
        "userVerificationDetails": [
            [
                {
                    "userVerificationMethod": "presence_internal"
                }
            ]
        ],
        "keyProtection": [
            "hardware",
            "secure_element",
            "remote_handle"
        ],
        "isKeyRestricted": false,
        "isFreshUserVerificationRequired": false,
        "matcherProtection": [
            "on_chip"
        ],
        "cryptoStrength": 128,
        "attachmentHint": [
            "external",
            "wired"
        ],
        "attestationRootCertificates": [
            "MIIDHjCCAgagAwIBAgIEG0BT9zANBgkqhkiG9w0BAQsFADAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowLjEsMCoGA1UEAxMjWXViaWNvIFUyRiBSb290IENBIFNlcmlhbCA0NTcyMDA2MzEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC/jwYuhBVlqaiYWEMsrWFisgJ+PtM91eSrpI4TK7U53mwCIawSDHy8vUmk5N2KAj9abvT9NP5SMS1hQi3usxoYGonXQgfO6ZXyUA9a+KAkqdFnBnlyugSeCOep8EdZFfsaRFtMjkwz5Gcz2Py4vIYvCdMHPtwaz0bVuzneueIEz6TnQjE63Rdt2zbwnebwTG5ZybeWSwbzy+BJ34ZHcUhPAY89yJQXuE0IzMZFcEBbPNRbWECRKgjq//qT9nmDOFVlSRCt2wiqPSzluwn+v+suQEBsUjTGMEd25tKXXTkNW21wIWbxeSyUoTXwLvGS6xlwQSgNpk2qXYwf8iXg7VWZAgMBAAGjQjBAMB0GA1UdDgQWBBQgIvz0bNGJhjgpToksyKpP9xv9oDAPBgNVHRMECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjANBgkqhkiG9w0BAQsFAAOCAQEAjvjuOMDSa+JXFCLyBKsycXtBVZsJ4Ue3LbaEsPY4MYN/hIQ5ZM5p7EjfcnMG4CtYkNsfNHc0AhBLdq45rnT87q/6O3vUEtNMafbhU6kthX7Y+9XFN9NpmYxr+ekVY5xOxi8h9JDIgoMP4VB1uS0aunL1IGqrNooL9mmFnL2kLVVee6/VR6C5+KSTCMCWppMuJIZII2v9o4dkoZ8Y7QRjQlLfYzd3qGtKbw7xaF1UsG/5xUb/Btwb2X2g4InpiB/yt/3CpQXpiWX/K4mBvUKiGn05ZsqeY1gx4g0xLBqcU9psmyPzK+Vsgw2jeRQ5JlKDyqE0hebfC1tvFu0CCrJFcw=="
        ],
        "icon": "data:image/png;base64,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"
    }
}

Sample body for request - FIDO2 device

{
    "aaguid": "e1a96183-5016-4f24-b55b-e3ae23614cc6",
    "metadataStatement": {
        "legalHeader": "https://fidoalliance.org/metadata/metadata-statement-legal-header/",
        "aaguid": "e1a96183-5016-4f24-b55b-e3ae23614cc6",
        "description": "ATKey.Pro CTAP2.0",
        "authenticatorVersion": 2,
        "protocolFamily": "fido2",
        "schema": 3,
        "upv": [
            {
                "major": 1,
                "minor": 0
            }
        ],
        "authenticationAlgorithms": [
            "secp256r1_ecdsa_sha256_raw"
        ],
        "publicKeyAlgAndEncodings": [
            "cose"
        ],
        "attestationTypes": [
            "basic_full"
        ],
        "userVerificationDetails": [
            [
                {
                    "userVerificationMethod": "fingerprint_internal",
                    "baDesc": {
                        "selfAttestedFRR": 0,
                        "selfAttestedFAR": 0,
                        "maxTemplates": 0,
                        "maxRetries": 0,
                        "blockSlowdown": 0
                    }
                },
                {
                    "userVerificationMethod": "presence_internal"
                },
                {
                    "userVerificationMethod": "passcode_internal"
                }
            ]
        ],
        "keyProtection": [
            "hardware"
        ],
        "isKeyRestricted": false,
        "isFreshUserVerificationRequired": true,
        "matcherProtection": [
            "on_chip"
        ],
        "attachmentHint": [
            "external"
        ],
        "attestationRootCertificates": [
            "MIIBzDCCAXGgAwIBAgIBATAKBggqhkjOPQQDAjBiMQswCQYDVQQGEwJTRTESMBAGA1UECgwJQVRLZXlDQTAwMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRswGQYDVQQDExJBdXRoZW50cmVuZCBDQSAwMDAwIBcNMTYwMjI2MDgxMTA2WhgPMjA1MDAyMjUwODExMDZaMGIxCzAJBgNVBAYTAlNFMRIwEAYDVQQKDAlBVEtleUNBMDAxIjAgBgNVBAsMGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xGzAZBgNVBAMTEkF1dGhlbnRyZW5kIENBIDAwMDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAJcWqeCxga9KJbFO2TZdjcgrtZAgfi8TXKu+v5lcR5ceb5GJYxyoCjhueESL3ddmMIkpGyhsEEtfFUyBwsyFVCjFjAUMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0EAwIDSQAwRgIhAPuVS4Pm2KFXdUMi5Pb/Xy+gCROOuRPZ6I57vWc0EvkBAiEA8aRCnXppAffCEOQBJ7vlgwiiHMXA2tpWX+ObvVKxXbM=",
            "MIIBzDCCAXGgAwIBAgIBATAKBggqhkjOPQQDAjBiMQswCQYDVQQGEwJTRTESMBAGA1UECgwJQVRLZXlDQTAwMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMRswGQYDVQQDExJBdXRoZW50cmVuZCBDQSAwMDAwIBcNMTYwMjI2MDgxMTA2WhgPMjA1MDAyMjUwODExMDZaMGIxCzAJBgNVBAYTAlNFMRIwEAYDVQQKDAlBVEtleUNBMDAxIjAgBgNVBAsMGUF1dGhlbnRpY2F0b3IgQXR0ZXN0YXRpb24xGzAZBgNVBAMTEkF1dGhlbnRyZW5kIENBIDAwMDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAJcWqeCxga9KJbFO2TZdjcgrtZAgfi8TXKu+v5lcR5ceb5GJYxyoCjhueESL3ddmMIkpGyhsEEtfFUyBwsyFVCjFjAUMBIGA1UdEwEB/wQIMAYBAQECAQAwCgYIKoZIzj0EAwIDSQAwRgIhAMqIc/Qtr+jZbnrJB7g7W8r/DHmDe+IyFvzwpzdSrxEXAiEAtXcixZznhcDzlnIqFqkIJRGmvL9Yr6lVoP1ZkDeqmjk="
        ],
        "icon": "data:image/png;base64,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",
        "authenticatorGetInfo": {
            "versions": [
                "U2F_V2",
                "FIDO_2_0",
                "FIDO_2_1_PRE"
            ],
            "extensions": [
                "credBlob",
                "credProtect",
                "hmac-secret"
            ],
            "aaguid": "e1a9618350164f24b55be3ae23614cc6",
            "options": {
                "uv": true,
                "userVerificationMgmtPreview": true,
                "credMgmt": true,
                "uvBioEnroll": true,
                "rk": true,
                "plat": false,
                "clientPin": false,
                "up": true,
                "bioEnroll": true,
                "credentialMgmtPreview": true
            },
            "maxMsgSize": 2048,
            "pinUvAuthProtocols": [
                1
            ],
            "maxCredentialCountInList": 20,
            "maxCredentialIdLength": 128,
            "transports": [
                "usb"
            ],
            "algorithms": [
                {
                    "type": "public-key",
                    "alg": -7
                },
                {
                    "type": "public-key",
                    "alg": -8
                }
            ],
            "firmwareVersion": 10013
        }
    }
}

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.

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

Check Remembered Device data model