FACE AUTH 가이드

FACE AUTH는 기존 eKYC에서 확보한 Submission ID의 셀피(Reference)와 사용자의 최신 셀피(Target)를 비교해 동일인 여부를 즉시 확인하는 애드온 서비스입니다. 별도의 복잡한 과정 없이 셀피 한 번으로 재인증을 완료할 수 있습니다.

대표 활용 시나리오

비밀번호나 인증코드 없이 셀피 한 번으로 신원을 재확인하므로, 보안을 강화하면서도 사용자 마찰을 낮출 수 있습니다.

단말기 변경

금융기관에서 기기 변경·번호 변경 시 계정 도용 위험을 낮추기 위한 재인증 수단으로 사용합니다.

이상징후 감지 시 재인증

ATO 방지 - 고위험 로그인, 해외 접속, 대량 시도 탐지 시 추가 얼굴 인증으로 접근 차단/해제 정책을 적용합니다.

정기 본인 재확인

주기적 KYC Refresh - 고가치 서비스·규제 산업에서 주기적 동일인 확인 절차로 활용합니다.

비밀번호 분실/정보 변경

비밀번호 재설정, 결제수단·연락처 변경 등 중요 계정 변경 전 본인 확인 단계로 삽입합니다.

동작 방식 (3-Step)

전제조건

eKYC의 승인된 Submission이 존재해야 합니다. (Reference)

진행

Add-On URL 호출 (pid + Submission ID 포함) → 셀피 촬영

데스크톱 진입 시 QR 표시 → 모바일로 이어받아 촬영합니다.

판정/저장

등록본 vs 검증본 자동 비교 → 결과는 Auth ID(제출건)로 대시보드에 저장됩니다.

핵심 체크

승인된 Submission ID가 존재해야 합니다. (Reference)
FACE AUTH URL 사용 시 보안을 위해 암호화하여 사용해야 합니다.
임계값·라이브니스·가림(마스크/헬멧/모자 등) 정책은 프로젝트 옵션으로 제어할 수 있습니다.

FACE AUTH의 장점

장점	설명
빠른 재인증	신분증 재촬영 없이 셀피 한 번으로 완료
보안 보강	비밀번호·OTP와 병행하는 추가 요인으로 계정 보호
정책 유연성	얼굴 일치 임계값, 라이브니스, 가림 차단 등 상황별 세분화 설정
간단한 연동	기존 eKYC 프로젝트에 애드온 형태로 종속되어 운영 일관성 유지

프로젝트 생성 및 설정

FACE AUTH를 사용하려면 먼저 대시보드에서 Add-On 프로젝트를 만들고 정책(임계값·라이브니스·가림)을 설정합니다.

Step 1: Add-On 프로젝트 만들기

대시보드의 **애드온 메뉴 → ‘프로젝트 생성하기’**를 선택해 새 FACE AUTH 프로젝트를 만듭니다. 생성 즉시 eKYC 프로젝트와 종속 연결이 형성되며, Add-On URL과 API 키가 자동 매핑됩니다. Add-On 프로젝트는 연결된 eKYC 프로젝트와 같은 리전에 생성됩니다. 자세한 내용은 리전 안내를 참고하세요.

경로: 대시보드 > 애드온 > 프로젝트 생성하기

Step 2: 프로젝트 정보 설정

설정 화면에서 프로젝트명·로고를 지정하고, 인증 제출 완료 후 이동할 버튼/URL을 설정합니다.

설정 항목	설명
Project Name	인증 시작화면에 제목으로 표시됩니다
Project Status	Service(정상 운영) / Closed(인증 불가)
Add on Logo	첫 번째 인증 화면 상단에 표시 (미설정 시 ARGOS 로고 표시)
Return URL	인증 완료 후 사용자가 리디렉션되는 URL

Step 3: 정책 (임계값) 설정

임계값은 낮을수록 완화, 높을수록 엄격합니다. 서비스 리스크·UX 목표에 맞춰 단계적으로 조정하세요.

정책 항목	설명	권장값
얼굴 인증 임계값	eKYC 승인자의 얼굴과 동일인 여부 판단 기준	98점
라이브니스	촬영 셀피가 실제 살아있는 사람인지 판단 (Passive/Active)	70점
얼굴 가려짐	인증 중 얼굴이 다른 물체로 가려지지 않았는지 확인	-

얼굴 가려짐과 얼굴 가림 임계점은 동시에 사용할 수 없습니다.

특수 환경 옵션:

머리 가림 임계점: 안전모 착용이 필요한 환경 (바이크, 건설 현장 등)
얼굴 가림 임계점: 마스크 착용이 필요한 환경 (병원, 건설 현장 등)

Step 4: Add-On URL 파라미터 및 암호화 설정

FACE AUTH URL을 사용하기 위해서는 필수 파라미터를 등록해야 합니다. 필수 파라미터:

파라미터	설명
`pid`	Add-On 프로젝트 ID (URL 경로/파라미터에 포함)
`sid`	eKYC Submission ID (승인 상태에서만 Add-On 인증가능, 암호화 필요)

선택 파라미터:

파라미터	설명
`authUserId`	해당 유저에게 부여할 유저 ID (관리자 서비스의 유저 ID 또는 eKYC에서 사용한 `userId`와 동일하게 지정 가능)
`authCf1`	추가 정보 저장용 커스텀 필드 (예: 이메일 주소)
`authCf2`	추가 정보 저장용 커스텀 필드
`authCf3`	추가 정보 저장용 커스텀 필드
`token`	1회성 URL을 위한 Token ID (토큰 만료 조건 설정 활성화 시 동작)
`lang`	FACE AUTH 화면 표시 언어 (ISO 639-1 소문자 코드, 예: `en`). 암호화 대상 아님 — `encrypted` 밖에 평문으로 붙입니다. 미설정 시 모바일은 기기 언어, PC는 브라우저 언어를 따릅니다

선택 파라미터도 모두 encrypted 내부에 포함해서 전달합니다. 각 파라미터의 상세 정의는 FaceAuth 시작하기 — 요청 파라미터들에 대한 정의를 참고하세요.

URL 패턴 예시:

...?pid={ADDON_PID}&encrypted={encrypted}

encrypted의 평문은 JSON 객체를 직렬화한 문자열입니다. Submission ID는 sid, Token ID는 token 키로 담습니다. 쿼리 스트링 형태(sid=...&token=...)로 이어붙여 암호화하면 인식되지 않습니다.

암호화 대상 평문

{ "sid": "{승인된 eKYC Submission ID}", "token": "{tokenId}" }

암호화 결과(Base64)는 URL에 붙이기 전 반드시 URL 인코딩하세요. 상세 절차는 FaceAuth 시작하기 — FaceAuth에 접근하기 위한 QueryString을 참고하세요.

토큰 만료 조건 설정

Token ID를 통하여 제한된 접근 제어를 구성할 수 있습니다.

만료 조건	설명
횟수 기반 만료	토큰이 1회 사용 시 해당 Token ID를 만료 처리
시간 기반 만료	토큰이 1회 사용된 기점으로 시간을 측정하여 Token ID를 만료 처리

만료 트리거링 조건은 FACE AUTH 첫 화면에서 “시작하기” 버튼이 클릭되었을 때입니다.

리턴 URL 설정

AddOn Return URL 카드에서 인증 종료 후 사용자가 돌아갈 URL과 함께 전달할 필드를 지정합니다. 선택한 필드는 아래 순서대로 리턴 URL 쿼리에 붙습니다.

설정 항목	쿼리 파라미터	값
Authentication Result	`authStatus`	인증 결과 (`approved` / `rejected`)
Authentication ID	`authId`	FaceAuth submission 키값. 조회·이미지·삭제 API에 사용
User ID	`authUserId`	진입 시 전달한 유저 ID
Custom Field #1~#3	`authCf1` ~ `authCf3`	진입 시 전달한 커스텀 필드

최종 리턴 URL 예시

https://yourapp.com/callback?authStatus={authStatus}&authId={authId}&authUserId={authUserId}&authCf1={authCf1}&authCf3={authCf3}

토글	동작
Skip Result Page	FaceAuth 결과 화면을 건너뛰고 바로 리턴 URL로 이동합니다. 리턴 URL을 입력하지 않으면 동작하지 않습니다.
Encryption	선택한 필드를 `encrypted` 파라미터 하나로 묶어 전달합니다. 복호화는 AES-256-ECB이며 ID Check 리턴 URL과 같은 방식입니다.

리턴 URL 파라미터는 사용자 브라우저를 거쳐 전달되므로 위·변조될 수 있습니다. authStatus만 보고 승인 처리하지 마시고, authId로 단건 조회 API를 호출해 서버에서 재확인하거나 FaceAuth 웹훅을 사용하세요.

ID Check(라이브폼)의 리턴 URL은 본 프로젝트의 연동 정보 > 리턴 URL에서 별도로 관리되며 전달 파라미터도 다릅니다. 두 설정은 서로 독립적입니다. → 리턴 URL 가이드

사용자에게 제공하기

FACE AUTH는 두 가지 방식으로 제공할 수 있습니다.

A. Add-On URL (권장)
B. API 기반 연동

사용자에게 Add-On URL을 열도록 안내하면 웹 화면에서 셀피 촬영으로 재인증을 진행합니다.필수 파라미터:

pid={AddOn Project ID} — URL 쿼리스트링에 평문으로 포함
encrypted={...} — {"sid": "{승인된 eKYC Submission ID}"} JSON을 AES-256으로 암호화한 값, URL 인코딩 필수 (Step 4 참고)

이 페이지의 라이브폼 URL은 US 리전 프로젝트 기준입니다. KR 리전 프로젝트는 호스트가 form-kr.argosidentity.com입니다. 자세한 내용은 리전 안내를 참고하세요.

URL 패턴

https://form.argosidentity.com/face-auth?pid={ADDON_PID}&encrypted={encrypted}

데스크톱 → 모바일 전환: PC에서 열면 QR 코드가 표시되어 사용자가 휴대폰으로 스캔 후 촬영을 이어갑니다.

체크리스트

✅ 링크/버튼에 Add-On URL 연결
✅ sid가 누락/미승인이 아닌지 확인 (eKYC가 approved 상태여야 함)
✅ sid 등 보안 파라미터는 반드시 encrypted 내부에 포함되어야 함 (평문 노출 금지)
✅ 데스크톱 유입이 많다면 QR 전환 안내 문구를 상단 고정 배치

동작 확인 (스모크 테스트)

승인된 submissionId로 Add-On URL 호출 시 인증 화면이 나타나는지
PC 진입 시 QR 노출 및 모바일 전환이 자연스러운지
촬영 후 결과가 Add-On 제출건(Auth ID)으로 저장·조회되는지

AUTH ID - 인증 결과 확인

Auth ID는 FACE AUTH(애드온) 한 건의 결과(제출건)를 지칭합니다. 등록본(이전에 eKYC로 승인된 얼굴)과 이번 셀피(검증본)를 비교한 동일인 판정, 적용된 정책 스냅샷, 처리 타임라인이 함께 기록됩니다.

대시보드에서 결과 확인

대시보드 > 애드온(FACE AUTH) 프로젝트 > 제출건(Auth ID) 목록 > 상세 보기

목록 화면에서 확인 가능한 정보:

시간
AUTH ID (TARGET)
Submission ID (Reference)
Status

상세 화면에서 확인 가능한 정보:

정책 스냅샷
점수/임계값
라이브니스·가림 결과
비교 이미지
로그

Auth ID 상세 정보

필드	설명
Authentication ID	해당 제출건의 고유 식별자
Submission ID	제출 시 비교대상으로 참조한 기 승인된 제출건
Status	Approved, Rejected로 인증에 대한 결과 표시
Policy	해당 제출건이 진행될 때 적용된 프로젝트 옵션
FACE Similarity	인증 시 측정된 셀피 이미지 간의 유사도
Liveness	제출된 셀피의 라이브니스 점수
Face Occluded	Pass / Fail로 얼굴이 가려졌는지 판단한 결과

Reference 정보에서 Selfie를 우선적으로 비교하며, Selfie가 없는 경우 신분증의 초상화를 차순으로 호출하여 비교합니다.

웹훅으로 실시간 연동

FACE AUTH가 완료되어 최종 결과가 나오면, 기존 ID Check 프로젝트에 등록된 Webhook URL로 결과가 자동 전송됩니다. 트리거 타입: "faceAuth"

{
  "webhook_trigger": "faceAuth",
  "Authentication_id": "AUTH_...",
  "data": {
    "Submission_id": "SUB_...",
    "Auth_Status": "approved | rejected",
    "Create_Time": "UTC+0",
    "User_id": "optional",
    "cf1": "optional",
    "cf2": "optional",
    "cf3": "optional",
    "reference": {
      "userid": "optional",
      "email": "optional",
      "cf": { "cf1": "optional", "cf2": "optional", "cf3": "optional" }
    }
  }
}

구현 체크리스트

✅ Webhook URL 등록(프로젝트 단위) 및 2xx 응답으로 수신 확인
✅ 중복 수신 방지 처리: Authentication_id 기준 중복 확인
✅ 타임존 처리: Create_Time(UTC+0) → 필요 시 내부 표준 시각 변환
✅ 키 매핑: Submission_id, User_id, cf1~3로 내부 사용자/요청과 매핑
✅ 감사 로깅: 원본 페이로드와 라우팅 결과를 함께 저장

대시보드로 관리자의 운영 친화적 판독, 개발팀은 웹훅으로 시스템 자동화를 동시에 진행할 수 있습니다. Auth ID 단위로 상태·점수·정책·타임라인을 일관되게 보고, 웹훅의 Authentication_id/Submission_id로 내부 시스템 플로우에 즉시 연결하여 사용하세요.

빠른 도입을 위한 체크리스트

프로젝트 생성

대시보드 → 애드온에서 FACE AUTH 프로젝트를 생성합니다.

정책값 설정

얼굴 일치 임계값 / 라이브니스 / 가림 차단(ON/OFF)을 설정합니다.

eKYC 승인 Submission 확보

Reference로 사용할 승인된 eKYC Submission이 필요합니다.

호출 설계

Add-On URL에 pid + Submission ID 포함 (데스크톱→QR→모바일 흐름 고려)

결과 확인 루틴

대시보드에서 Auth ID(제출건) 상태·정책·비교 결과를 모니터링합니다.

운영 팁

정책 초기값은 다소 보수적으로 시작 → 실제 서비스 데이터를 보며 임계값을 단계적으로 튜닝
모니터링 지표: 재인증 성공률, 중도이탈률, 평균 인증 소요시간, 위험 이벤트 차단률, 재설정/변경 완료율
UX 설계: 데스크톱 진입률이 높다면 QR 전환 플로우를 분명히 안내하고, 모바일 사용자는 인증 가이드를 최소 문구로 제공

FaceAuth 시작하기

Add-On 서비스의 전체 개요를 확인합니다.

POST/Face Auth API

API를 통한 FACE AUTH 연동 방법을 확인합니다.

FACE AUTH 웹훅

FACE AUTH 결과를 웹훅으로 수신하는 방법을 확인합니다.

암호화 가이드

URL 암호화 방법을 확인합니다.

Face Auth URL 검증 및 에러 처리

에러 코드와 사용자에게 노출되는 문구를 확인합니다.

애드온

FaceAuth

대표 활용 시나리오

단말기 변경

이상징후 감지 시 재인증

정기 본인 재확인

비밀번호 분실/정보 변경

동작 방식 (3-Step)

FACE AUTH의 장점

프로젝트 생성 및 설정

Step 1: Add-On 프로젝트 만들기

Step 2: 프로젝트 정보 설정

Step 3: 정책 (임계값) 설정

Step 4: Add-On URL 파라미터 및 암호화 설정

토큰 만료 조건 설정

리턴 URL 설정

사용자에게 제공하기

POST/Face Auth API 문서

동작 확인 (스모크 테스트)

AUTH ID - 인증 결과 확인

대시보드에서 결과 확인

Auth ID 상세 정보

웹훅으로 실시간 연동

빠른 도입을 위한 체크리스트

운영 팁

관련 문서

FaceAuth 시작하기

POST/Face Auth API

FACE AUTH 웹훅

암호화 가이드

Face Auth URL 검증 및 에러 처리

​대표 활용 시나리오

단말기 변경

이상징후 감지 시 재인증

정기 본인 재확인

비밀번호 분실/정보 변경

​동작 방식 (3-Step)

​FACE AUTH의 장점

​프로젝트 생성 및 설정

​Step 1: Add-On 프로젝트 만들기

​Step 2: 프로젝트 정보 설정

​Step 3: 정책 (임계값) 설정

​Step 4: Add-On URL 파라미터 및 암호화 설정

​토큰 만료 조건 설정

​리턴 URL 설정

​사용자에게 제공하기

POST/Face Auth API 문서

​동작 확인 (스모크 테스트)

​AUTH ID - 인증 결과 확인

​대시보드에서 결과 확인

​Auth ID 상세 정보

​웹훅으로 실시간 연동

​빠른 도입을 위한 체크리스트

​운영 팁

​관련 문서

FaceAuth 시작하기

POST/Face Auth API

FACE AUTH 웹훅

암호화 가이드

Face Auth URL 검증 및 에러 처리

대표 활용 시나리오

동작 방식 (3-Step)

FACE AUTH의 장점

프로젝트 생성 및 설정

Step 1: Add-On 프로젝트 만들기

Step 2: 프로젝트 정보 설정

Step 3: 정책 (임계값) 설정

Step 4: Add-On URL 파라미터 및 암호화 설정

토큰 만료 조건 설정

리턴 URL 설정

사용자에게 제공하기

동작 확인 (스모크 테스트)

AUTH ID - 인증 결과 확인

대시보드에서 결과 확인

Auth ID 상세 정보

웹훅으로 실시간 연동

빠른 도입을 위한 체크리스트

운영 팁

관련 문서