Authentification biométrique : avertissements et codes

L’authentification biométrique combine un contrôle de détection du vivant avec une correspondance faciale 1:1 facultative par rapport au visage de référence déterminé lors de la création de la session (le portrait_image fourni ou le visage enregistré de l’utilisateur retrouvé via vendor_data). Chaque étape émet ses propres avertissements dans le payload de décision V3. Cette page détaille chaque code, où il apparaît et la façon dont les seuils se traduisent par un statut de session final.

Vue d’ensemble

Lorsqu’une session d’authentification biométrique s’exécute, Didit :

Capture un selfie en direct à l’aide de l’action 3D, du flash ou de la détection passive du vivant (method : ACTIVE_3D, FLASHING ou PASSIVE).
Extrait le visage le plus grand de la capture et évalue la détection du vivant.
Si le workflow inclut la Correspondance faciale, compare le visage capturé au visage de référence de la session (portrait_image fourni ou visage enregistré de l’utilisateur).
Inscrit le résultat de chaque étape ainsi que tout avertissement dans la décision de la session.

Les avertissements conservent la structure partagée de l’objet d’avertissement utilisée sur l’ensemble de la plateforme : feature, risk, additional_data, log_type, short_description, long_description et node_id.

Où apparaissent les avertissements

Clé de réponse de décision	Balise de fonctionnalité sur l’avertissement	Quand il se déclenche
`liveness_checks[].warnings[]`	`LIVENESS`	Évaluation de la vivacité, qualité du visage, luminance, visages multiples et vérifications de liste de blocage / liste d’autorisation / visages dupliqués.
`face_matches[].warnings[]`	`FACEMATCH`	Correspondance faciale par rapport au visage de référence de la session (`portrait_image` fourni ou visage enregistré de l’utilisateur).

Dans une session d’authentification biométrique standard, il y a un élément dans chaque tableau. Dans les workflows multi-instances, le champ node_id présent sur chaque avertissement permet de distinguer l’étape qui l’a généré.

Conditions de refus automatique

Les avertissements suivants entraînent toujours le refus de leur étape (log_type: "error"), quelle que soit la configuration de votre workflow :

Risque	Fonctionnalité	Pourquoi il refuse automatiquement
`FACE_IN_BLOCKLIST`	`LIVENESS`	Le visage correspond à une entrée de votre liste de blocage des visages.
`NO_FACE_DETECTED`	`LIVENESS`	Aucun visage n’a été détecté lors de la capture de vivacité, ou l’utilisateur a épuisé ses tentatives de capture.
`LIVENESS_FACE_ATTACK`	`LIVENESS`	Une attaque par présentation a été détectée (masque, relecture sur écran, usurpation de type deepfake).
`NO_REFERENCE_IMAGE`	`FACEMATCH`	Aucune image de référence n’était disponible pour effectuer la comparaison. Lorsqu’il se déclenche, `LOW_FACE_MATCH_SIMILARITY` est supprimé.

Lorsque NO_FACE_DETECTED se déclenche, LOW_LIVENESS_SCORE est supprimé (il n’y a aucun visage à évaluer).

Seuils et actions configurables

Ces avertissements font l’objet d’une notation puis sont associés à un statut selon les seuils et actions que vous définissez par workflow :

Risque	Fonctionnalité	Comportement configurable
`LOW_LIVENESS_SCORE`	`LIVENESS`	Score inférieur ou égal au seuil d’examen → `In Review` ; inférieur ou égal au seuil de refus → `Declined`.
`LOW_FACE_MATCH_SIMILARITY`	`FACEMATCH`	Score inférieur ou égal au seuil d’examen (70 par défaut) → `In Review` ; inférieur ou égal au seuil de refus (50 par défaut) → `Declined`.
`LOW_FACE_QUALITY`	`LIVENESS`	Seuil d’examen (15 par défaut) → `In Review` ; seuil de refus (0 par défaut, c.-à-d. refus désactivé) → `Declined`. Détection passive du vivant uniquement.
`LOW_FACE_LUMINANCE`	`LIVENESS`	Inférieur au seuil de luminance minimale (20 par défaut) : Aucune action / Examen (par défaut) / Refus. Détection passive du vivant uniquement.
`HIGH_FACE_LUMINANCE`	`LIVENESS`	Supérieur au seuil de luminance maximale (80 par défaut) : Aucune action / Examen (par défaut) / Refus. Détection passive du vivant uniquement.
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	Aucune action (par défaut) / Examen / Refus lorsque plusieurs visages sont capturés. Détection passive du vivant uniquement.
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	Une action partagée pour les visages dupliqués : Aucune action (par défaut) / Examen / Refus pour les correspondances avec les visages approuvés ou importés d’autres utilisateurs.
`DUPLICATED_FACE_NAME_MISMATCH`	`LIVENESS`	Action dédiée (`face_liveness_duplicated_face_name_mismatch_action`) : Aucune action / Examen (par défaut) / Refus. Émis aux côtés de `DUPLICATED_FACE` lorsque l’identité de la session correspondante ne concorde pas avec le nom déterminé de cette session — voir Avertissements de vivacité.

POSSIBLE_FACE_IN_BLOCKLIST (LIVENESS) n’est pas configurable — une correspondance avec une liste de blocage à score de confiance plus faible est toujours transmise pour examen (log_type: "warning").

Nouvelles tentatives de capture

Les échecs causés uniquement par des risques corrigibles liés à la qualité de capture (score faible, absence de visage, qualité, luminance, visages multiples — et faible similarité lors de la correspondance faciale) entrent dans une boucle de nouvelle tentative avant que le statut ne devienne définitif : l’utilisateur dispose d’un maximum de face_liveness_max_attempts / face_match_max_attempts tentatives au total (3 par défaut, configurable de 2 à 5 par nœud de workflow). Lorsque le nombre de tentatives alloué est épuisé, le statut calculé de la dernière tentative s’applique et LIVENESS_MAX_ATTEMPTS_EXCEEDED ou FACE_MATCH_MAX_ATTEMPTS_EXCEEDED est consigné avec le type information pour en garder une trace.

Avertissements de détection du vivant

L’API renvoie exactement ces chaînes short_description et long_description :

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	Low liveness score	The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.
`NO_FACE_DETECTED`	No Face Detected in liveness	The system couldn’t identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.
`LIVENESS_FACE_ATTACK`	Liveness Face Attack	The system detected a potential attempt to bypass the liveness check.
`FACE_IN_BLOCKLIST`	Face in blocklist	The system identified a face in the blocklist, which means the face is not allowed to be verified.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possible face in blocklist	The system identified a possible face in the blocklist, which means the face is not allowed to be verified.
`FACE_IN_ALLOWLIST`	Face in allowlist	The face matched the application’s face allowlist, so duplicate-face actions were skipped for this signal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Possible face in allowlist	The face possibly matched the application’s face allowlist, so possible duplicate-face actions were skipped for this signal.
`DUPLICATED_FACE`	Duplicated face from other approved session	The system identified a duplicated face from another approved session, requiring further investigation.
`POSSIBLE_DUPLICATED_FACE`	Possible duplicated face from other approved session	The system identified a possible duplicate face from another approved session, requiring further investigation.
`DUPLICATED_FACE_NAME_MISMATCH`	Duplicated face under a different name	The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.
`MULTIPLE_FACES_DETECTED` (Passif uniquement)	Multiple faces detected	Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.
`LOW_FACE_QUALITY` (Passif uniquement)	Low face quality	The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.
`LOW_FACE_LUMINANCE` (Passif uniquement)	Low face luminance	The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.
`HIGH_FACE_LUMINANCE` (Passif uniquement)	High face luminance	The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	Maximum liveness attempts exceeded	The maximum number of liveness capture attempts has been reached. The last attempt’s computed status (decline or review) has been applied.

Les correspondances avec une liste de blocage, une liste d’autorisation et les doublons comportent additional_data avec la session correspondante (blocklisted_session_id / allowlisted_session_id / duplicated_session_id, le *_session_number correspondant et api_service). Un seul de ces six codes apparaît par rapport. DUPLICATED_FACE_NAME_MISMATCH fait exception : il est émis en plus de DUPLICATED_FACE, jamais à sa place, lorsque l’identité de la session correspondante ne concorde pas avec le nom résolu de cette session. Son additional_data ajoute name_match_score aux mêmes champs de session dupliquée. Un nom écrit dans un système d’écriture différent de chaque côté n’est pas considéré comme une non-concordance lorsque les documents d’identité des deux sessions partagent un État de délivrance, un numéro de document ou personnel exact et une date de naissance non contradictoire. Voir Avertissements de détection du vivant.

Avertissements de correspondance faciale

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	Low face match similarity	The facial features of the provided image don’t closely match the reference image, suggesting a potential identity mismatch.
`NO_REFERENCE_IMAGE`	No source image found for performing face match	A reference image for facial comparison is missing, preventing the system from completing the face matching process.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	Maximum face match attempts exceeded	The maximum number of face match capture attempts has been reached. The last attempt’s computed status (decline or review) has been applied.

Exemple : refusé en raison d’une attaque faciale

{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}

Exemple : en cours d’examen en raison d’une faible similarité

{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}

Le score (58.70) se situe entre le seuil de refus (50 par défaut) et le seuil d’examen (70 par défaut), de sorte que l’avertissement porte log_type: "warning" et que le statut de correspondance faciale est In Review. Dans cet exemple, l’avertissement s’est déclenché sur une session dont le session_id est 11111111-2222-3333-4444-555555555555 — source_image_session_id porte l’identifiant propre à la session car la référence provenait du portrait enregistré lors de la création de la session.

Types d’avertissements

Chaque risque se voit attribuer un type d’avertissement en fonction de la configuration de votre application. Les avertissements se répartissent en trois catégories de gravité :

Voir aussi

Rapport d'authentification biométrique

Où liveness_checks[] et face_matches[] apparaissent dans la décision V3.

Avertissements de détection du vivant

Référence complète des avertissements de détection du vivant, y compris la correspondance de visages en doublon.

Avertissements de correspondance faciale

Référence complète des avertissements de correspondance faciale pour les comparaisons 1:1.