生体認証レポート：JSONスキーマ

生体認証レポートは、Diditが既存ユーザーの再検証結果を返すための仕組みです。ワークフローは新たにライブネスチェックを実行し、ワークフローで顔照合が有効な場合は、セッション作成時に確定した参照顔画像(指定したportrait_image、またはvendor_dataで検索されたユーザーの保存済み顔画像)との1:1顔照合も実行します。どちらのチェックも、V3のセッション判定レスポンスに標準の機能項目として含まれます。

ライブネスチェックと保存済みポートレートに対する顔照合を組み合わせたDiditの生体認証レポート

概要

生体認証はワークフローの種類(workflow_type: "biometric_authentication")であり、独立したレスポンスオブジェクトではありません。ワークフローを実行すると、次の項目が出力されます。

ライブセルフィーを撮影し、なりすましの有無をスコアリングするライブネスチェックが1件。
撮影した顔とセッション作成時に確定した参照顔画像を比較する顔照合が1件(ワークフローで顔照合が有効な場合のみ)。

ワークフローに顔照合が含まれる場合、セッション作成時には必ず参照顔画像が必要です。portrait_image(base64エンコードされた画像、最大2MB)を送信するか、省略した場合はDiditがvendor_dataのユーザーについて保存済みの顔画像を再利用します。優先順位は、承認済みのライブネス顔画像、ePassportのチップ写真、身分証明書類のポートレート、手動で登録されたプロフィール顔画像の順です。portrait_imageも保存済みの顔画像もない場合、セッション作成は400と

{"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."}

を返します。いずれの場合も、確定した参照画像は新しいセッションに記録されるため、顔照合項目のsource_image_session_idにはそのセッション自身のsession_idが設定されます(これは、参照画像が同じセッション内で撮影された書類のポートレートではなく、セッションの保存済みポートレートに由来することを示します。同じセッション内で撮影された身分証明書類のポートレートに由来する場合、このフィールドはnullになります)。

表示される場所

判定レスポンスのキー	件数	項目のスキーマ
`liveness_checks[]`	ライブネスのステップごとに1件(生体認証では通常1件)	data-models#liveness-check
`face_matches[]`	顔照合のステップごとに1件(ライブネスのみのワークフローでは`null`)	data-models#face-match

どちらの配列も、ワークフロータイプがbiometric_authenticationであるセッションでは、GET /v3/session/{sessionId}/decision/によって返されます。これらは常に配列であり、単一のオブジェクトになることはありません。また、それぞれのステップがデータを生成するまではnullです。各項目にはnode_idが含まれるため、複数のインスタンスを持つワークフローでもステップを区別できます。

スキーマリファレンス

全フィールドの一覧はdata-modelsページで一元的に定義されており、これらの機能を含むすべてのレポートが同じ情報源を共有します。

ライブネス項目のスキーマ: status、method、score、reference_image、video_url、age_estimation、matches[]、face_quality、face_luminance、warnings[]、node_id。
顔照合項目のスキーマ: status、score、source_image_session_id、source_image、target_image、warnings[]、node_id。
警告エントリの構造: feature、risk、additional_data、log_type、short_description、long_description、node_id。

ステータス値

liveness_checks[].statusとface_matches[].statusはどちらも、共通の機能ライフサイクル(機能レベルのステータス)を使用します。

ステータス	意味
`Not Finished`	ステップがまだ最終結果を生成していません(ユーザーが完了していない、または離脱した)。ステップが開始される前は、判定レスポンス内の配列は単に`null`です。
`Approved`	チェックが設定されたすべてのしきい値を満たしました。
`In Review`	スコアがレビュー範囲に入ったか、設定可能な警告がレビューに設定されていました。
`Declined`	スコアが却下しきい値以下だったか、自動却下の警告が発生しました(顔への攻撃、顔の未検出、ブロックリスト登録済みの顔、顔照合用の参照画像なし)。
`Resub Requested`	レビュアーがユーザーにこのステップの再試行を求めました。

セッション全体のstatusは両方の項目を集約します。いずれかの機能がDeclinedであればセッションは却下され、いずれかがIn ReviewであればセッションはIn Reviewになり、それ以外の場合は(すべての機能が完了した後に)Approvedになります。しきい値の動作と警告コードの全一覧については、生体認証の警告を参照してください。

例: ライブネス+顔照合(承認済み)

例は簡略化しています。完全な判定エンベロープには、session_url、metadata、callback、reviews、contact_details、expected_details、environment、created_at、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
}

例: ライブネスのみ(ワークフローで顔照合が無効)

{
  "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
}

ライブネスのみモードはワークフローの設定です。顔照合が無効な場合、セッション作成時に参照顔画像は不要で、face_matchesはnullのままです。顔照合が有効な場合、portrait_imageを省略してもライブネスのみにはフォールバックしません。Diditはvendor_dataのユーザーについて保存済みの顔画像を再利用し、保存済みの顔画像が存在しない場合、セッション作成は400で失敗します。

例: 類似度が低く顔照合が却下された場合

{
  "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"
        }
      ]
    }
  ]
}

セキュリティに関する注意

reference_image、video_url、source_image、target_imageは、限られた有効期間(デフォルトでは4時間)が経過すると失効する署名付きURLです。これらは生体データを指しているため、キャッシュしたり公開したりしないでください。認証結果(ステータス、スコア、source_image_session_id)は自社側で保存し、新しいURLが必要な場合は判定エンドポイントを再度呼び出してください。

生体認証の警告

警告コード、しきい値、自動却下の条件。

ライブネスレポート

liveness_checks[]項目の全フィールドリファレンス。

顔照合レポート

face_matches[]項目の全フィールドリファレンス。

認証

検証

モニタリング

プラットフォーム

生体認証レポート：JSONスキーマ

概要

表示される場所

スキーマリファレンス

ステータス値

例: ライブネス+顔照合(承認済み)

例: ライブネスのみ(ワークフローで顔照合が無効)

例: 類似度が低く顔照合が却下された場合

セキュリティに関する注意

関連情報

生体認証の警告

ライブネスレポート

顔照合レポート

​概要

​表示される場所

​スキーマリファレンス

​ステータス値

​例: ライブネス+顔照合(承認済み)

​例: ライブネスのみ(ワークフローで顔照合が無効)

​例: 類似度が低く顔照合が却下された場合

​セキュリティに関する注意

​関連情報

生体認証の警告

ライブネスレポート

顔照合レポート

概要

表示される場所

スキーマリファレンス

ステータス値

例: ライブネス+顔照合(承認済み)

例: ライブネスのみ(ワークフローで顔照合が無効)

例: 類似度が低く顔照合が却下された場合

セキュリティに関する注意

関連情報