---
title: "Biometric settings - Rest PKI Core"
description: "Every field of the Biometric settings section of the Rest PKI Core dashboard: capture and verification providers, external identity verification, minimum match levels, return URL whitelist and subject identifier formats."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/configs/biometric-settings"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-11-05"
---

# Biometric settings - Rest PKI Core

The **Biometric settings** section of the dashboard holds your subscription's defaults for biometric sessions: which providers
capture and verify the face, when the face is checked against an external source, how close two faces must be to match, and
which return URLs and subject identifiers are accepted.

Each field starts on **Use system default**, which follows the instance's setting (on your own instances, the `Bio` section of
`appsettings`; see [Instance defaults](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/configs/biometric-settings#instance-defaults)). Choose a value to override it for your subscription only. Where a
session parameter exists for the same thing, the value sent when the session is created wins over both.

## Opening the settings

1. Sign in to the dashboard of your instance.
2. On the left menu, click **Settings**.
3. Find the **Biometric settings** section. It shows the value in effect for each field.
4. Click **Edit**, change the fields, and click **Save**. **Discard** leaves without saving.

**Reset configurations** sets every field of the section back to **Use system default**.

The geolocation capture has a section of its own: see [Geolocation configuration](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/configs/geolocation).

## Providers and platform

| Field | Values | System default | What it does |
|---|---|---|---|
| **Standard face capture provider** | **FaceTec Liveness3d**, **FortFace Liveness** | **FaceTec Liveness3d** | The provider that captures the face and checks liveness. Only the providers available on the instance are listed. A session's `FaceCaptureProvider` parameter wins over it ([see details](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#face-capture-session-parameters)). |
| **Face identity verification provider** | **Datavalid**, **FortFace** | None | The external service used by [external identity verification](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/configs/biometric-settings#external-identity-verification). Datavalid is Serpro's service, which compares the face with the photo in Brazilian government records. |
| **Platform preference** | **No preference**, **Suggest mobile device**, **Require mobile device** | **No preference** | Whether the user is offered, or required, to continue on a phone through a QR code. A session's `PlatformPreference` parameter wins over it ([see details](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#general-parameters)). |

## External identity verification

External identity verification compares the captured face with an outside record of the person, through the **Face identity
verification provider**, in addition to Rest PKI Core's own checks. Two fields turn it on:

| Field | System default | What it does |
|---|---|---|
| **Standard verify face identity externally** | Disabled | Default for [enrollment](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/enrollment) sessions. When enabled, an enrollment checks the face with the provider before the subject is enrolled, and fails with `FaceIdentityVerificationFailed` unless the provider answers with a good match. A session's `VerifyFaceIdentityExternally` parameter wins over it. |
| **Authentication sessions: Verify face identity externally on no match** | Disabled | When a [face authentication](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/authentication) does not match the subject's enrolled face, the face is checked with the provider instead of the session failing at once. The session succeeds if the provider answers with a good match, and fails with `FaceIdentityVerificationFailed` otherwise. Authentication sessions have no parameter to override it: this field alone decides. |

**Authentication sessions: Verify face identity externally on no match** can't be enabled while manual validation is enabled for
your subscription: both decide what happens on a no match, so saving is refused.

### Permission to use it (v5.1.0)

Since v5.1.0, external identity verification needs two things, both off by default:

- on the instance, `Bio:EnableExternalIdentityVerifications` set to `true` (on your own instances, in `appsettings`);
- on your subscription, the general permission **Can perform external identity verifications**, which a system administrator
  grants in **Sys Admin**. On your own instances, `Bio:DefaultCanPerformExternalIdentityVerifications` set to `true` grants it to
  every subscription that has no value of its own.

While either is missing:

- the section shows a note saying which one is missing;
- saving is refused when it would turn either field above on, or change the **Face identity verification provider**. Turning
  them off, and saving the other fields, always works;
- a session that asks for an external verification is refused when it is created, with the error code
  `ExternalIdentityVerificationsNotEnabled`.

> **Warning**
>
> An authentication session asks for an external verification whenever **Authentication sessions: Verify face identity externally
> on no match** is in effect, even through **Use system default**. If your subscription can't perform external identity
> verifications, and that field is enabled (or the system default is), **every face authentication fails** with
> `ExternalIdentityVerificationsNotEnabled`. Set the field to **Disabled** explicitly, not to **Use system default**. The same goes
> for enrollments and **Standard verify face identity externally**, unless every enrollment sends `VerifyFaceIdentityExternally`
> as `false`.

## Matching

| Field | System default | What it does |
|---|---|---|
| **Enable low quality face authentication** | Disabled | Lets face authentication accept lower-quality images. While it is enabled, a **Face authentication** minimum match level above **5** is treated as **5**, which lowers your application's security. Saving it enabled asks you to confirm. |
| **Registration sessions: identify and reject duplicates** | Disabled | Shown only when face identifications (1:N) are enabled for your subscription. When enabled, an enrollment searches the subjects already enrolled and fails with `DuplicatesFound` if the face is already there under another identifier. |

### Minimum match levels

Each slider sets how close two faces must be for the comparison to pass. A higher level is stricter: fewer impostors get
through, and more genuine users are turned away. The refresh button next to a slider returns it to the system default.

| Slider | Compares | System default | Range |
|---|---|---|---|
| **Enrollment image quality check - Minimum self match level (2D/2D)** | The enrollment image with itself, to check it is sharp enough to be used later. Below the level, the enrollment fails with `FaceNotFoundWithSufficientQuality` | 6 | 1 to 6 |
| **Face authentication - Minimum match level (3D/2D)** | The captured face with the enrolled one, when only one of them is 3D (for example, a capture with 3D liveness and a subject enrolled from an image) | 9 | 1 to 9 |
| **Face authentication - Minimum match level (2D/2D)** | The captured face with the enrolled one, when neither is 3D | 5 | 1 to 6 |
| **Document face matching (FaceTec) - Minimum match level (2D/2D)** | A 2D face with the photo on the identification document | 6 | 1 to 6 |
| **Document face matching (FaceTec) - Minimum match level (3D/2D)** | A face captured with 3D liveness with the photo on the identification document | 7 | 1 to 7 |
| **Document face matching (FortFace) - Minimum match level** | The face with the photo on the identification document, when FortFace captures the document | 10 | 1 to 16 |

The document sliders apply to sessions that capture an identification document (the `CaptureIdentificationDocument` parameter
of an enrollment, and [ID capture](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/id-capture) sessions).

## Return URL whitelist

The authorities (scheme and host, plus the port when it isn't the default one) that a session's `ReturnUrl` may point to, such
as `https://contoso.com`. Paths are removed when you add an entry.

- **Empty** (default): any return URL is accepted, and the section shows "Whitelist disabled - all return URLs will be accepted".
- **With entries**: a session whose `ReturnUrl` points to another authority is refused when it is created, with the error code
  `BioSessionReturnUrlAuthorityNotWhitelisted`.

The list holds up to 50 entries (`Bio:MaxBioSessionReturnUrlWhitelistedAuthorities` on your own instances). Sessions that use
`TrustedOrigin` instead of `ReturnUrl` are not affected ([see the difference](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#frontend-flows)).

## Allowed subject identifier formats

Which formats of `SubjectIdentifier` an enrollment accepts: **CPF (11 digits, no punctuation)**, **CNPJ (14 digits, no
punctuation)** and **Email (valid address)**.

| On the screen | Enrollments accepted |
|---|---|
| **Use system defaults** on | Whatever the instance allows (`Bio:AllowedSubjectIdentifierFormats`). The section shows that default |
| **Use system defaults** off, nothing ticked | Any identifier, even when the instance restricts them |
| **Use system defaults** off, some formats ticked | Only those formats |

An enrollment with another format is refused when it starts, with the error code `InvalidSubjectIdentifier`. The setting doesn't
affect authentications or subjects already enrolled. See [Subject identifier formats configuration](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/configs/subject-identifier-formats).

## Instance defaults

On your own (on-premises) instances, **Use system default** means these keys of the `Bio` section of `appsettings`:

| Field | Key | Default |
|---|---|---|
| **Standard face capture provider** | `Bio:DefaultFaceCaptureProvider` | `FaceTecLiveness3d` |
| **Face identity verification provider** | `Bio:DefaultFaceIdentityVerificationProvider` | None |
| **Platform preference** | `Bio:DefaultPlatformPreference` | `NoPreference` |
| **Standard verify face identity externally** | `Bio:DefaultVerifyFaceIdentityExternally` | `false` |
| **Authentication sessions: Verify face identity externally on no match** | `Bio:AuthenticationVerifyFaceIdentityExternallyOnNoMatch` | `false` |
| **Enable low quality face authentication** | `Bio:UseLowQualityFaceAuthentication` | `false` |
| **Registration sessions: identify and reject duplicates** | `Bio:Identification:DefaultEnrollmentIdentifyDuplicates` | `false` |
| **Enrollment image quality check** | `Bio:Enrollment2dValidationFaceTecMinMatchLevel` | `6` |
| **Face authentication (3D/2D)** | `Bio:AuthenticationFaceTecMatch3d2dMinMatchLevel` | `9` |
| **Face authentication (2D/2D)** | `Bio:AuthenticationFaceTecMatch2d2dMinMatchLevel` | `5` |
| **Document face matching (FaceTec) (2D/2D)** | `Bio:DocumentFaceMatch2d2dMinMatchLevel` | `6` |
| **Document face matching (FaceTec) (3D/2D)** | `Bio:DocumentFaceMatch3d2dMinMatchLevel` | `7` |
| **Document face matching (FortFace)** | `Bio:FortFaceDocumentFaceMatchMinMatchLevel` | `10` |
| **Allowed subject identifier formats** | `Bio:AllowedSubjectIdentifierFormats`, comma-separated: `CPF`, `CNPJ`, `EMAIL` | Empty (any format) |
| Permission to use external identity verification | `Bio:EnableExternalIdentityVerifications`, `Bio:DefaultCanPerformExternalIdentityVerifications` | `false`, `false` |

Two related settings exist only on the instance: `Bio:AuthenticationUpdateSubjectFaceOnExternalFaceIdentityGoodMatch` (default
`false`) replaces the subject's enrolled face with the new one after an external good match on a face authentication, and
`Bio:DatavalidGoodMatchMinLevel` and `Bio:DatavalidUncertainMatchMinLevel` (defaults `0.93` and `0.85`) set the similarity that
Datavalid must report for a good or an uncertain match.