PingOne Recognize

Liveness Settings

PingOne Recognize provides configurable liveness detection for the Mobile SDK. Liveness detection helps determine whether the captured face belongs to a live person. It protects against spoofing, an attack in which a bad actor attempts to mimic a genuine user.

Liveness level configuration

Use the liveness level to select the balance between security, usability, and processing time. The following table lists the available levels from lower to higher security:

Level Description Recommended use

DEVELOPMENT

Intended for development and testing only.

Do not use in production.

BALANCED

Prioritizes usability while providing liveness protection.

Lower-risk scenarios where reducing user friction is important.

LEVEL_1

Provides a practical balance between security, usability, and time to decision. This is the default level.

Most production scenarios.

LEVEL_2

Provides the highest security level, but can increase genuine-user rejection and the time required to complete liveness processing.

Higher-risk scenarios that require stronger protection against spoof attempts.

Higher liveness levels improve the ability to reject spoof attempts. They can also increase the chance that the system rejects a genuine user and the time required for the liveness decision. Choose the lowest level that meets the security requirements of your use case.

You configure the liveness level through the livenessConfiguration property on the enrollment, authentication, and de-enrollment configuration objects. Refer to LivenessSettings.LivenessConfiguration for the available values.

Liveness type

Use the mobileLivenessMode customer property to select how the Mobile SDK uses mobile and server-side liveness. The setting applies to enrollment, authentication, and enrollment from client state.

The supported modes are:

Mode Description

MOBILE_ONLY

Runs liveness on the mobile device only. This is the default mode and preserves the existing behavior.

MOBILE_ACTIVE_SERVER_FIRE_AND_FORGET

Runs mobile liveness as the active decision and sends the image to server-side liveness for shadow evaluation. The SDK records the server-side result for comparison, but the result doesn’t affect the user outcome.

MOBILE_AND_SERVER

Runs both mobile and server-side liveness. Both liveness decisions must pass for enrollment or authentication to succeed.

SERVER_ONLY

Uses server-side liveness as the active decision. The SDK sends the first frame that satisfies the local image filters and skips mobile liveness.
For all modes that use server-side liveness, the SDK sends the captured image to the PingOne Recognize backend. Confirm that this processing model meets your organization’s privacy and data-handling requirements before you enable it.

The liveness level remains part of the configuration when you enable mobile or server-side liveness. Contact the PingOne Recognize team for guidance on how the liveness level applies to server-side liveness.

Server-side liveness image requirements

For reliable server-side liveness processing, follow these image-acquisition guidelines:

  • Don’t crop the camera image. Preserve as much of the captured scene as possible, including the paper or phone border, because those areas can help detect an attack.

  • Aim for an image height of approximately 1080 – 1280 pixels. Use the camera’s native resolution when it’s close to this range. For example, 1920 × 1080 in landscape or 720 × 1280 in portrait mode.

  • Image height matters more than total resolution or image width. Both landscape and portrait orientations can work, but don’t crop the image to force a particular aspect ratio.

  • Avoid unnecessary resizing or other image manipulation because it can negatively affect machine-learning models.

  • Capture at a minimum of 8 frames per second (FPS).

  • If the camera can’t provide the preferred resolution, the SDK can use a lower resolution.

The current production server-side liveness setting uses JPEG quality 95. Data collection storage uses PNG with ZIP storage level 0 (no compression). Don’t apply lossy compression to data collection assets.

In SERVER_ONLY mode, the SDK sends the first frame that satisfies the local image filters. You must configure a server-side liveness endpoint to use server-side liveness. If you select a mode that uses server-side liveness without the required endpoint configuration, the SDK returns an error.

Configuring livenessEnvironmentAware

The livenessEnvironmentAware feature enforces stricter environmental checks during liveness and can add an additional layer of protection against certain biometric attacks. The default is false from SDK v5.3.3 and above.

On a limited set of devices, this can prevent some users from authenticating with PingOne Recognize, in which case the SDK returns 20021.

For security purposes, implementation details of this liveness feature are not documented here. Contact the PingOne Recognize team if you need deeper detail on the feature and the observed security/UX tradeoffs for true vs false.

Relax liveness checks for testing purposes

The following examples are for testing purposes only and help test the happy path for passing liveness checks.

Android

// ONLY FOR TEST

// Authentication Configuration
val authConfig = BiomAuthConfig(
        livenessConfiguration = LivenessSettings.LivenessConfiguration.DEVELOPMENT,
        livenessEnvironmentAware = false
)


// Enrollment Configuration
val enrollConfig = BiomEnrollConfig(
        livenessConfiguration = LivenessSettings.LivenessConfiguration.DEVELOPMENT,
        livenessEnvironmentAware = false
)


// De-Enrollment Configuration
val deEnrollConfig = BiomDeEnrollConfig(
        livenessConfiguration = LivenessSettings.LivenessConfiguration.DEVELOPMENT,
        livenessEnvironmentAware = false
)

iOS

// ONLY FOR TEST

// Authentication Configuration
let authConfig = BiomAuthConfig(
        livenessConfiguration: Keyless.LivenessConfiguration.DEVELOPMENT,
        livenessEnvironmentAware: false
)

// Enrollment Configuration
let enrollConfig = BiomEnrollConfig(
        livenessConfiguration: Keyless.LivenessConfiguration.DEVELOPMENT,
        livenessEnvironmentAware: false
)

// De-Enrollment Configuration
let deEnrollConfig = BiomDeEnrollConfig(
        livenessConfiguration: Keyless.LivenessConfiguration.DEVELOPMENT,
        livenessEnvironmentAware: false
)

Flutter

// ONLY FOR TEST

// Authentication Configuration
final authConfig = BiomAuthConfig(
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
    // livenessEnvironmentAware: false - not available yet
);

// Enrollment Configuration
final enrollConfig = BiomEnrollConfig(
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
    // livenessEnvironmentAware: false - not available yet
);

// De-Enrollment Configuration
final deEnrollConfig = BiomDeEnrollConfig(
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
    // livenessEnvironmentAware: false - not available yet
);

React Native

// ONLY FOR TEST

// Authentication Configuration
const authConfig = new BiomAuthConfig({
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
    livenessEnvironmentAware: false,
});

// Enrollment Configuration
const enrollConfig = new BiomEnrollConfig({
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
    livenessEnvironmentAware: false,
});

// De-Enrollment Configuration
const deEnrollConfig = new BiomDeEnrollConfig({
    livenessConfiguration: LivenessConfiguration.PASSIVE_STANDALONE_MEDIUM,
    livenessEnvironmentAware: false,
});