Biometrische Authentifizierung – Bericht: JSON-Schema

Der Bericht zur biometrischen Authentifizierung zeigt, wie Didit die erneute Verifizierung eines wiederkehrenden Benutzers zurückmeldet. Der Workflow führt eine neue Liveness-Prüfung durch und, wenn der Gesichtsabgleich im Workflow aktiviert ist, auch einen 1:1-Gesichtsabgleich mit dem bei der Sitzungserstellung ermittelten Referenzgesicht (das von Ihnen bereitgestellte portrait_image oder das über vendor_data abgefragte gespeicherte Gesicht des Benutzers). Beide Prüfungen erscheinen als standardmäßige Funktionselemente in der V3-Sitzungsentscheidungsantwort.

Didit-Bericht zur biometrischen Authentifizierung, der Liveness-Prüfung und Gesichtsabgleich mit einem gespeicherten Porträt kombiniert

Übersicht

Biometrische Authentifizierung ist ein Workflow-Typ (workflow_type: "biometric_authentication"), kein separates Antwortobjekt. Wenn der Workflow ausgeführt wird, erzeugt er:

Eine Liveness-Prüfung, die ein Live-Selfie erfasst und auf Spoofing bewertet.
Einen Gesichtsabgleich, der das erfasste Gesicht mit dem bei der Sitzungserstellung ermittelten Referenzgesicht vergleicht (nur wenn der Gesichtsabgleich im Workflow aktiviert ist).

Wann immer der Workflow den Gesichtsabgleich umfasst, erfordert die Sitzungserstellung ein Referenzgesicht. Senden Sie portrait_image (Base64-codiertes Bild, max. 2MB), oder lassen Sie es weg, sodass Didit das für den vendor_data-Benutzer bereits gespeicherte Gesicht wiederverwendet: zuerst ein genehmigtes Liveness-Gesicht, dann das ePass-Chipfoto, dann das Porträt aus dem Ausweisdokument, dann ein manuell registriertes Profilgesicht. Wenn weder portrait_image noch ein gespeichertes Gesicht verfügbar sind, gibt die Sitzungserstellung 400 mit

{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}

zurück. In beiden Fällen wird die ermittelte Referenz unter der neuen Sitzung erfasst, sodass source_image_session_id des Gesichtsabgleich-Elements auf die eigene session_id dieser Sitzung gesetzt wird (dies zeigt Ihnen an, dass die Referenz aus dem gespeicherten Porträt der Sitzung stammt und nicht aus einem in derselben Sitzung erfassten Dokumentenporträt, was das Feld auf null belassen würde).

Wo es erscheint

Schlüssel der Entscheidungsantwort	Plural	Element-Schema
`liveness_checks[]`	Eines pro Liveness-Schritt (üblicherweise 1 bei biometrischer Authentifizierung)	data-models#liveness-check
`face_matches[]`	Eines pro Gesichtsabgleich-Schritt (`null` in reinen Liveness-Workflows)	data-models#face-match

Beide Arrays werden von GET /v3/session/{sessionId}/decision/ für Sitzungen zurückgegeben, deren Workflow-Typ biometric_authentication ist. Sie sind immer Arrays – niemals einzelne Objekte – und jedes ist null, bis der jeweilige Schritt Daten erzeugt hat. Jedes Element enthält eine node_id, damit Workflows mit mehreren Instanzen Schritte eindeutig unterscheiden können.

Schema-Referenz

Die vollständige Feldliste wird einmal auf der Datenmodell-Seite definiert, damit jeder Bericht, der diese Funktionen enthält, dieselbe zentrale Referenz nutzt:

Liveness-Element-Schema – status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
Gesichtsabgleich-Element-Schema – status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
Struktur eines Warnungseintrags – feature, risk, additional_data, log_type, short_description, long_description, node_id.

Statuswerte

Sowohl liveness_checks[].status als auch face_matches[].status verwenden den gemeinsamen Funktionslebenszyklus (Statuswerte auf Funktionsebene):

Status	Bedeutung
`Not Finished`	Der Schritt hat noch kein Endergebnis geliefert (der Benutzer hat ihn nicht abgeschlossen oder abgebrochen). Bevor ein Schritt überhaupt beginnt, ist sein Array in der Entscheidungsantwort einfach `null`.
`Approved`	Die Prüfung hat alle konfigurierten Schwellenwerte bestanden.
`In Review`	Der Wert fiel in den Prüfbereich, oder eine konfigurierbare Warnung wurde auf Prüfung gesetzt.
`Declined`	Der Wert lag bei oder unter dem Ablehnungsschwellenwert, oder eine automatische Ablehnungswarnung wurde ausgelöst (Gesichtsangriff, kein Gesicht erkannt, Gesicht auf der Sperrliste, kein Referenzbild für den Gesichtsabgleich).
`Resub Requested`	Ein Prüfer hat den Benutzer aufgefordert, diesen Schritt zu wiederholen.

Der übergeordnete status der Sitzung fasst beide Elemente zusammen: Jede Funktion im Status Declined führt zur Ablehnung der Sitzung, jede im Status In Review setzt die Sitzung auf In Review, andernfalls Approved (nachdem jede Funktion abgeschlossen ist). Informationen zum Schwellenwertverhalten und die vollständige Liste der Warnungscodes finden Sie unter Warnungen zur biometrischen Authentifizierung.

Beispiel – Liveness + Gesichtsabgleich (genehmigt)

Die Beispiele sind gekürzt: Die vollständige Entscheidungsantwort enthält auch session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at und expires_at.

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}

Beispiel – Nur Liveness (Gesichtsabgleich im Workflow deaktiviert)

{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "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": []
    }
  ],
  "face_matches": null
}

Der reine Liveness-Modus ist eine Workflow-Konfiguration: Wenn der Gesichtsabgleich deaktiviert ist, wird bei der Sitzungserstellung kein Referenzgesicht benötigt und face_matches bleibt null. Wenn der Gesichtsabgleich aktiviert ist, fällt das Weglassen von portrait_image nicht auf den reinen Liveness-Modus zurück: Didit verwendet das für den vendor_data-Benutzer gespeicherte Gesicht wieder, und wenn kein gespeichertes Gesicht existiert, schlägt die Sitzungserstellung mit 400 fehl.

Beispiel – Gesichtsabgleich wegen geringer Ähnlichkeit abgelehnt

{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "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": "error",
          "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"
        }
      ]
    }
  ]
}

Sicherheitshinweis

reference_image, video_url, source_image und target_image sind signierte URLs, die nach einem begrenzten Gültigkeitsfenster (standardmäßig 4 Stunden) ablaufen. Sie verweisen auf biometrische Daten – speichern Sie sie nicht im Cache und machen Sie sie nicht öffentlich zugänglich. Speichern Sie das Verifizierungsergebnis (Status, Score, source_image_session_id) auf Ihrer Seite; rufen Sie den Entscheidungs-Endpoint erneut ab, wenn Sie neue URLs benötigen.

Warnungen zur biometrischen Authentifizierung

Warnungscodes, Schwellenwerte und Bedingungen für automatische Ablehnungen.

Liveness-Bericht

Vollständige Feldreferenz für liveness_checks[]-Elemente.

Gesichtsabgleich-Bericht

Vollständige Feldreferenz für face_matches[]-Elemente.

Authentifizierung

Verifizierung

Überwachung

Plattform

Biometrische Authentifizierung – Bericht: JSON-Schema

Übersicht

Wo es erscheint

Schema-Referenz

Statuswerte

Beispiel – Liveness + Gesichtsabgleich (genehmigt)

Beispiel – Nur Liveness (Gesichtsabgleich im Workflow deaktiviert)

Beispiel – Gesichtsabgleich wegen geringer Ähnlichkeit abgelehnt

Sicherheitshinweis

Verwandte Themen

Warnungen zur biometrischen Authentifizierung

Liveness-Bericht

Gesichtsabgleich-Bericht

​Übersicht

​Wo es erscheint

​Schema-Referenz

​Statuswerte

​Beispiel – Liveness + Gesichtsabgleich (genehmigt)

​Beispiel – Nur Liveness (Gesichtsabgleich im Workflow deaktiviert)

​Beispiel – Gesichtsabgleich wegen geringer Ähnlichkeit abgelehnt

​Sicherheitshinweis

​Verwandte Themen

Warnungen zur biometrischen Authentifizierung

Liveness-Bericht

Gesichtsabgleich-Bericht

Übersicht

Wo es erscheint

Schema-Referenz

Statuswerte

Beispiel – Liveness + Gesichtsabgleich (genehmigt)

Beispiel – Nur Liveness (Gesichtsabgleich im Workflow deaktiviert)

Beispiel – Gesichtsabgleich wegen geringer Ähnlichkeit abgelehnt

Sicherheitshinweis

Verwandte Themen