생체 인증 경고 및 코드

생체 인증은 라이브니스 검사와 세션 생성 시 확인된 기준 얼굴(제공된 portrait_image 또는 vendor_data로 조회된 사용자의 저장된 얼굴)과의 선택적 1:1 얼굴 대조를 결합합니다. 각 단계는 V3 결정 payload에 고유한 경고를 생성합니다. 이 페이지에서는 모든 코드, 표시 위치, 임계값이 최종 세션 상태로 변환되는 방식을 설명합니다.

개요

생체 인증 세션이 실행되면 Didit은 다음을 수행합니다.

3D Action, Flash 또는 Passive Liveness(method: ACTIVE_3D, FLASHING 또는 PASSIVE)를 사용하여 라이브 셀피를 캡처합니다.
캡처된 이미지에서 가장 큰 얼굴을 추출하고 라이브니스 점수를 산정합니다.
워크플로에 얼굴 대조가 포함된 경우, 캡처된 얼굴을 세션의 기준 얼굴(제공된 portrait_image 또는 사용자의 저장된 얼굴)과 비교합니다.
각 단계의 결과와 모든 경고를 세션 결정에 기록합니다.

경고는 플랫폼 전반에서 사용되는 공통 경고 객체 형태를 유지합니다: feature, risk, additional_data, log_type, short_description, long_description, node_id.

경고 표시 위치

결정 응답 키	경고의 기능 태그	발생 조건
`liveness_checks[].warnings[]`	`LIVENESS`	라이브니스 점수 산정, 얼굴 품질, 휘도, 다중 얼굴 감지, 차단 목록/허용 목록/중복 얼굴 검사 시.
`face_matches[].warnings[]`	`FACEMATCH`	세션의 기준 얼굴(제공된 `portrait_image` 또는 사용자의 저장된 얼굴)을 대상으로 한 얼굴 대조 시.

일반적인 생체 인증 세션에서는 각 배열에 하나의 항목이 포함됩니다. 다중 인스턴스 워크플로에서는 각 경고의 node_id를 통해 해당 경고를 생성한 단계를 구분할 수 있습니다.

자동 거부 조건

다음 경고는 워크플로 구성 방식과 관계없이 항상 해당 단계를 거부(log_type: "error")합니다.

위험	기능	자동 거부 이유
`FACE_IN_BLOCKLIST`	`LIVENESS`	얼굴이 얼굴 차단 목록의 항목과 일치합니다.
`NO_FACE_DETECTED`	`LIVENESS`	라이브니스 캡처 중 얼굴이 감지되지 않았거나, 사용자가 캡처 재시도 횟수를 모두 소진했습니다.
`LIVENESS_FACE_ATTACK`	`LIVENESS`	프레젠테이션 공격(가면, 화면 재생, 딥페이크 계열 스푸핑)이 감지되었습니다.
`NO_REFERENCE_IMAGE`	`FACEMATCH`	비교를 수행할 기준 이미지가 없습니다. 이 경고가 발생하면 `LOW_FACE_MATCH_SIMILARITY`는 생략됩니다.

NO_FACE_DETECTED가 발생하면 점수를 산정할 얼굴이 없으므로 LOW_LIVENESS_SCORE는 생략됩니다.

설정 가능한 임계값 및 작업

이러한 경고는 점수가 산정된 후 각 워크플로에 설정한 임계값 및 작업을 통해 상태로 매핑됩니다.

위험	기능	설정 가능한 동작
`LOW_LIVENESS_SCORE`	`LIVENESS`	점수가 검토 임계값 이하인 경우 → `In Review`, 거부 임계값 이하인 경우 → `Declined`.
`LOW_FACE_MATCH_SIMILARITY`	`FACEMATCH`	점수가 검토 임계값(기본값 70) 이하인 경우 → `In Review`, 거부 임계값(기본값 50) 이하인 경우 → `Declined`.
`LOW_FACE_QUALITY`	`LIVENESS`	검토 임계값(기본값 15) → `In Review`, 거부 임계값(기본값 0, 즉 거부 비활성화) → `Declined`. Passive Liveness 전용.
`LOW_FACE_LUMINANCE`	`LIVENESS`	최소 휘도 임계값(기본값 20) 미만: 작업 없음 / 검토(기본값) / 거부. Passive Liveness 전용.
`HIGH_FACE_LUMINANCE`	`LIVENESS`	최대 휘도 임계값(기본값 80) 초과: 작업 없음 / 검토(기본값) / 거부. Passive Liveness 전용.
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	둘 이상의 얼굴이 캡처된 경우: 작업 없음(기본값) / 검토 / 거부. Passive Liveness 전용.
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	두 경고에 공통으로 적용되는 중복 얼굴 작업: 다른 사용자의 승인되었거나 가져온 얼굴과 일치하는 경우 작업 없음(기본값) / 검토 / 거부.
`DUPLICATED_FACE_NAME_MISMATCH`	`LIVENESS`	별도 작업(`face_liveness_duplicated_face_name_mismatch_action`): 작업 없음 / 검토(기본값) / 거부. 일치하는 세션의 신원이 이 세션에서 확인된 이름과 일치하지 않을 때 `DUPLICATED_FACE`와 함께 생성됩니다. 자세한 내용은 라이브니스 경고를 참고하세요.

POSSIBLE_FACE_IN_BLOCKLIST(LIVENESS)는 설정할 수 없습니다. 신뢰도가 낮은 차단 목록 일치는 항상 검토(log_type: "warning")로 라우팅됩니다.

캡처 재시도

해결 가능한 캡처 품질 위험(낮은 점수, 얼굴 미감지, 품질, 휘도, 다중 얼굴, 그리고 얼굴 대조 시 낮은 유사도)으로만 인한 실패는 상태가 확정되기 전에 재시도 루프로 들어갑니다. 사용자는 face_liveness_max_attempts / face_match_max_attempts에 설정된 횟수만큼, 최대 총 시도 횟수(기본값 3회, 워크플로 노드당 2~5회 구성 가능)까지 시도할 수 있습니다. 시도 횟수가 모두 소진되면 마지막 시도에서 계산된 상태가 적용되며, 이를 기록하기 위해 LIVENESS_MAX_ATTEMPTS_EXCEEDED 또는 FACE_MATCH_MAX_ATTEMPTS_EXCEEDED가 information으로 로깅됩니다.

라이브니스 경고

API는 다음과 같은 정확한 short_description 및 long_description 문자열을 반환합니다.

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	낮은 라이브니스 점수	라이브니스 검사 결과 점수가 낮게 나왔으며, 이는 실제 얼굴이 아닌 표현물을 사용했거나 생체 인식 데이터의 품질이 낮을 가능성을 나타냅니다.
`NO_FACE_DETECTED`	라이브니스에서 얼굴 미감지	시스템이 라이브니스 검사 중 얼굴을 식별하지 못했습니다. 이는 이미지 품질 저하, 부적절한 위치 지정 또는 기술적 문제로 인한 것일 수 있습니다.
`LIVENESS_FACE_ATTACK`	라이브니스 얼굴 공격	시스템이 라이브니스 검사를 우회하려는 잠재적 시도를 감지했습니다.
`FACE_IN_BLOCKLIST`	차단 목록에 포함된 얼굴	시스템이 차단 목록에서 얼굴을 식별했습니다. 즉, 해당 얼굴은 인증이 허용되지 않습니다.
`POSSIBLE_FACE_IN_BLOCKLIST`	차단 목록에 포함되었을 가능성이 있는 얼굴	시스템이 차단 목록에 포함되었을 가능성이 있는 얼굴을 식별했습니다. 즉, 해당 얼굴은 인증이 허용되지 않습니다.
`FACE_IN_ALLOWLIST`	허용 목록에 포함된 얼굴	해당 얼굴이 애플리케이션의 얼굴 허용 목록과 일치하여 이 신호에 대한 중복 얼굴 작업이 건너뛰어졌습니다.
`POSSIBLE_FACE_IN_ALLOWLIST`	허용 목록에 포함되었을 가능성이 있는 얼굴	해당 얼굴이 애플리케이션의 얼굴 허용 목록과 일치했을 가능성이 있어 이 신호에 대한 중복 얼굴 가능성 관련 작업이 건너뛰어졌습니다.
`DUPLICATED_FACE`	승인된 다른 세션의 중복 얼굴	시스템이 승인된 다른 세션에서 중복된 얼굴을 식별하여 추가 조사가 필요합니다.
`POSSIBLE_DUPLICATED_FACE`	승인된 다른 세션의 중복 가능성이 있는 얼굴	시스템이 승인된 다른 세션에서 중복 가능성이 있는 얼굴을 식별하여 추가 조사가 필요합니다.
`DUPLICATED_FACE_NAME_MISMATCH`	다른 이름으로 중복된 얼굴	동일한 얼굴이 이미 다른 세션에서 승인되었으나 다른 이름으로 등록되어 있습니다. 중복된 대상의 신원이 본 세션에 신고된 신원과 일치하지 않으며, 이는 신원 사기의 강력한 지표입니다.
`MULTIPLE_FACES_DETECTED` (패시브 전용)	여러 얼굴 감지됨	라이브니스 이미지에서 여러 얼굴이 감지되었습니다. 시스템은 라이브니스 검증 및 얼굴 비교에 가장 큰 얼굴을 사용하지만, 여러 얼굴이 존재하면 추가 검토가 필요할 수 있습니다.
`LOW_FACE_QUALITY` (패시브 전용)	낮은 얼굴 품질	얼굴 이미지 품질이 허용 임계값 미만이어서 라이브니스 감지의 신뢰도에 영향을 미칠 수 있습니다. 이는 카메라 해상도, 초점 또는 압축 왜곡 때문일 수 있습니다.
`LOW_FACE_LUMINANCE` (패시브 전용)	낮은 얼굴 밝기	얼굴 이미지가 너무 어두워 라이브니스 감지의 정확도에 영향을 미칠 수 있습니다. 더 나은 조명 환경을 권장합니다.
`HIGH_FACE_LUMINANCE` (패시브 전용)	높은 얼굴 밝기	얼굴 이미지가 너무 밝거나 과다 노출되어 라이브니스 감지의 정확도에 영향을 미칠 수 있습니다. 조명을 줄이거나 직접 조명을 피하는 것을 권장합니다.
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	최대 라이브니스 시도 횟수 초과	라이브니스 캡처 최대 시도 횟수에 도달했습니다. 마지막 시도의 계산된 상태(거부 또는 검토)가 적용되었습니다.

차단 목록, 허용 목록 및 중복 일치 항목에는 일치하는 세션 정보(blocklisted_session_id / allowlisted_session_id / duplicated_session_id, 일치하는 *_session_number 및 api_service)가 포함된 additional_data가 전달됩니다. 보고서당 이 6개 코드 중 하나만 표시됩니다. DUPLICATED_FACE_NAME_MISMATCH는 예외입니다. 일치하는 세션의 신원이 본 세션의 확인된 이름과 일치하지 않을 때, DUPLICATED_FACE를 대체하지 않고 추가로 생성됩니다. 이 코드의 additional_data에는 동일한 중복 세션 필드에 name_match_score가 추가됩니다. 양쪽 세션의 신분증 문서가 발급 국가, 정확한 문서 번호 또는 개인 식별 번호, 모순되지 않는 생년월일을 공유하는 경우 서로 다른 문자 체계로 표기된 이름은 불일치로 처리되지 않습니다. 라이브니스 경고를 참고하십시오.

얼굴 대조 경고

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	낮은 얼굴 대조 유사도	제공된 이미지의 얼굴 특징이 기준 이미지와 밀접하게 일치하지 않아 신원이 일치하지 않을 가능성을 나타냅니다.
`NO_REFERENCE_IMAGE`	얼굴 대조를 수행할 소스 이미지를 찾을 수 없음	얼굴 비교를 위한 기준 이미지가 누락되어 시스템이 얼굴 대조 프로세스를 완료할 수 없습니다.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	최대 얼굴 대조 시도 횟수 초과	얼굴 대조 캡처 최대 시도 횟수에 도달했습니다. 마지막 시도의 계산된 상태(거부 또는 검토)가 적용되었습니다.

예시 — 얼굴 공격으로 거부됨

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

예시 — 낮은 유사도로 검토 중

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

점수(58.70)가 거부 임계값(기본값 50)과 검토 임계값(기본값 70) 사이에 위치하므로 경고에 log_type: "warning"이 포함되고 얼굴 대조 상태는 In Review가 됩니다. 이 예시에서 경고는 session_id가 11111111-2222-3333-4444-555555555555인 세션에서 발생했습니다. 기준 이미지가 세션 생성 시 저장된 인물 사진에서 가져온 것이므로 source_image_session_id에는 해당 세션 자체의 id가 전달됩니다.

경고 유형

애플리케이션 설정에 따라 각 위험에 경고 유형이 할당됩니다. 경고는 세 가지 심각도 카테고리로 나뉩니다.

생체 인증 보고서

V3 결정에서 liveness_checks[] 및 face_matches[]가 표시되는 위치입니다.

라이브니스 경고

중복 얼굴 일치를 포함한 전체 라이브니스 경고 레퍼런스입니다.

얼굴 대조 경고

1:1 비교를 위한 전체 얼굴 대조 경고 레퍼런스입니다.

인증

인증

모니터링

플랫폼

생체 인증 경고 및 코드

개요

경고 표시 위치

자동 거부 조건

설정 가능한 임계값 및 작업

캡처 재시도

라이브니스 경고

얼굴 대조 경고

예시 — 얼굴 공격으로 거부됨

예시 — 낮은 유사도로 검토 중

경고 유형

관련 항목

생체 인증 보고서

라이브니스 경고

얼굴 대조 경고

​개요

​경고 표시 위치

​자동 거부 조건

​설정 가능한 임계값 및 작업

​캡처 재시도

​라이브니스 경고

​얼굴 대조 경고

​예시 — 얼굴 공격으로 거부됨

​예시 — 낮은 유사도로 검토 중

​경고 유형

​관련 항목

생체 인증 보고서

라이브니스 경고

얼굴 대조 경고

개요

경고 표시 위치

자동 거부 조건

설정 가능한 임계값 및 작업

캡처 재시도

라이브니스 경고

얼굴 대조 경고

예시 — 얼굴 공격으로 거부됨

예시 — 낮은 유사도로 검토 중

경고 유형

관련 항목