FaceAuth 시작하기 - ARGOS Identity

함께 볼 문서

대시보드에서 FaceAuth 프로젝트를 만들고 정책(임계값·라이브니스·가림)과 토큰 만료를 설정하는 방법 → FACE AUTH 가이드
애드온 공통 사항(API 키 발급, 요청 할당량, 응답 HTTP 상태 코드) → 애드온 시작하기

FaceAuth 진행 방식 — 2가지 선택지

FaceAuth는 다음 두 가지 방식으로 제공할 수 있습니다. 별도 카메라 UI 구현 없이 Active Liveness까지 활용할 수 있는 Face Auth URL 방식을 권장합니다.

A. Face Auth URL (권장)

ARGOS가 호스팅하는 페이지(Liveform과 유사)에서 셀피를 촬영합니다. 고객사가 카메라 UI를 직접 구현할 필요가 없으며, 프로젝트 정책에서 라이브니스(Passive/Active) 와 가림(마스크/헬멧) 차단 옵션을 활성화할 수 있습니다.

B. POST /faceauth API

고객사 앱에서 카메라 UI를 직접 구현하고 촬영한 faceImage 파일을 API로 전송합니다. Active Liveness가 지원되지 않습니다 — 단순 얼굴 유사도만 비교됩니다.

휴대폰 화면 재생·사진 캡쳐 등 스푸핑 시도가 우려된다면 URL 방식을 사용하세요. POST API 방식은 전달된 이미지 한 장만 유사도로 판정하므로 실제 촬영 여부를 검증하지 못합니다. URL 방식은 프로젝트 정책에서 라이브니스 임계값 을 설정하여 화면 재생·정지 사진 등의 스푸핑을 차단할 수 있습니다.

대시보드에서 정책(임계값·라이브니스·가림)을 설정하는 방법과 두 방식의 활용 사례는 FACE AUTH 가이드에서 확인하세요. 이 문서의 나머지 섹션은 A. Face Auth URL 방식의 파라미터와 인증 흐름을 다룹니다. B. POST API 방식은 POST/Faceauth 페이지를 참고하세요.

FaceAuth에 접근하기 위한 QueryString

FaceAuth는 ID check의 하위 프로젝트로서 관리자는 원하는 만큼의 프로젝트를 생성할 수 있고, FaceAuth URL 방식으로 유저가 추가 인증을 받기 위해선 Add-on 프로젝트 내의 Face Auth URL을 사용합니다.
셀피 사진이 존재하는 ID document나 Knowledge-based에서 승인 받은 submission_Id를 참조하기 위해선 encrypted 쿼리 파라미터로 URL에 추가해야 하며, 보안을 위해 항상 암호화된 상태로 사용해야 합니다.
암호화는 FaceAuth 프로젝트 내의 API 키를 사용해야 하며, AES-256을 사용합니다.
자세한 방법은 쿼리 스트링 암호화를 확인하세요.

암호화 대상 평문은 JSON입니다 — 쿼리 스트링 형식이 아닙니다.sid=...&authUserId=... 처럼 key=value를 &로 이어붙인 문자열을 암호화하면 sid가 인식되지 않아 인증이 시작되지 않습니다. JSON 객체를 직렬화(JSON.stringify)한 문자열을 암호화해서 encrypted 값으로 사용하세요.이 경우 오류 코드 페이지가 아니라 “페이지를 찾을 수 없습니다” 화면이 표시되어 원인을 알기 어렵습니다. 증상별 확인 순서는 Face Auth URL 검증 및 에러 처리를 참고하세요.

쿼리 스트링 없이는 Face Auth가 실행되지 않습니다.pid만 붙인 URL로는 인증이 시작되지 않으며, 참조할 sid를 암호화해 encrypted에 담아 전달해야 합니다. 누락 시 PV-40015 오류 페이지로 이동합니다.

1단계 — 암호화할 평문(JSON) 준비

{
  "sid": "{submission_Id}"
}

{
  "sid": "{submission_Id}",
  "authUserId": "{user Id}",
  "authCf1": "{additional_info}",
  "authCf2": "{additional_info}",
  "authCf3": "{additional_info}",
  "token": "{any tokenId}"
}

2단계 — FaceAuth 프로젝트 API 키로 AES-256 암호화 후 URL 조립

Face Auth URL 구조 (이 형태만으로는 실행되지 않음)

  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}

암호화된 값을 encrypted에 담은 형태 (실행되는 형태)

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

encrypted 값은 반드시 URL 인코딩해야 합니다.AES-256 암호화 결과(Base64)에는 +, /, = 문자가 포함됩니다. 인코딩 없이 URL에 붙이면 +가 공백으로 해석되어 복호화 자체가 실패하고 sid를 읽을 수 없습니다. encodeURIComponent(또는 각 언어의 URL 인코딩 함수)를 적용하세요.

Node.js 전체 예시

const crypto = require('crypto');

function encrypt(data, apiKey) {
  const hashedKey = crypto.createHash('sha256').update(apiKey).digest();
  const cipher = crypto.createCipheriv('aes-256-ecb', hashedKey, null);
  return cipher.update(data, 'utf8', 'base64') + cipher.final('base64');
}

// 1단계: 평문은 JSON 객체를 직렬화한 문자열
const queryData = JSON.stringify({
  sid: 'submission_12345',
  authUserId: 'user123',
});

// 2단계: FaceAuth 프로젝트의 API 키로 암호화 후 URL 인코딩
const encrypted = encrypt(queryData, FACEAUTH_API_KEY);
const faceAuthUrl =
  `https://form.argosidentity.com/face-auth?pid=${FACEAUTH_PROJECT_ID}` +
  `&encrypted=${encodeURIComponent(encrypted)}`;

pid와 lang은 암호화 대상이 아니며 encrypted 밖에 평문으로 붙입니다.

요청 파라미터들에 대한 정의

string

필수

FaceAuth 프로젝트 생성 시, 부여되는 프로젝트의 고유 번호 (URL에 자동적으로 붙여서 나옵니다.)

string

필수

ID document나 Knowledge-based를 통해서 승인 받은 submission_Id. (구분을 위해서 sid를 사용합니다.)

string

관리자가 부여할 해당 유저의 유저 Id (관리자 서비스 내의 유저 Id가 될 수도 있고, ID document나 Knowledge-based에서 사용한 userId와 동일하게 부여할 수도 있습니다.)

string

관리자가 추가로 부여할 해당 유저의 추가 정보들 (예: email 주소 등등)

string

관리자가 추가로 부여할 해당 유저의 추가 정보들 (authCf1과 동일)

string

관리자가 추가로 부여할 해당 유저의 추가 정보들 (authCf1과 동일)

string

보안을 위해서 관리자가 해당 url에 추가할 token 입니다.
주의사항!: 해당 token은 프라이빗 모드의 사전등록 token과는 별개로 작동됩니다.

FaceAuth token의 작동방식

Token은 사용자가 FaceAuth를 통해 인증할 때, 각 사용자에게 고유한 URL을 부여하기 위해 설계되었습니다.
Token을 적용하려면 FaceAuth 프로젝트에서 토큰 만료 조건 설정 옵션을 활성화해야 하며, 다음과 같은 방식으로 동작합니다.

횟수 기반 만료: 토큰이 한 번 사용되면 해당 Token ID가 즉시 만료 처리됩니다.
시간 기반 만료: 토큰이 한 번 사용된 시점을 기준으로 시간이 경과하면 해당 Token ID가 만료 처리됩니다.

이 토큰은 메인 프로젝트의 프라이빗 모드 토큰이나 사전 등록 토큰과는 별개로 동작합니다.
예를 들어, token에는 관리자가 설정한 임의의 tokenId를 지정할 수 있고, 메인 프로젝트에서 사용한 token을 재사용 하더라도 별개로 보기 때문에 작동됩니다. FaceAuth 프로젝트에서 토큰 만료 조건 설정 옵션을 활성화에 대한 가이드는 FACE AUTH 가이드 — 토큰 만료 조건 설정을 참고하세요.

string

Face Auth 화면의 표시 언어입니다. ISO 639-1 소문자 코드를 사용합니다 (예: en, ko). 암호화 대상이 아니며 encrypted 밖에 평문으로 붙입니다 (예: ?pid={faceAuth_projectId}&encrypted={encrypted}&lang=en). 미설정 시 모바일은 기기 설정 언어, PC는 브라우저 언어를 따릅니다. 지원 언어 목록은 라이브폼 지원 언어를 참고하세요.

승인된 건 중, 셀피 사진이 존재하지 않는 경우에는 신분증의 초상화 이미지를 대신 사용합니다.

Face Auth URL 검증 및 에러 처리

QueryString 검증 실패, 사전 로드 실패, 인증 실패 시 발생하는 에러 코드와 사용자에게 실제로 노출되는 문구를 단계별로 확인하세요.

FaceAuth API 엔드포인트

POST/FaceAuth

Faceauth 제출

GET/FaceAuth

Faceauth 조회

GET/FaceAuth/Image

FaceAuth 이미지 조회

DELETE/FaceAuth

Faceauth 삭제

웹훅

Faceauth

FaceAuth 웹훅

Token ID 만료

Token ID 만료 웹훅

​FaceAuth 진행 방식 — 2가지 선택지

A. Face Auth URL (권장)

B. POST /faceauth API

​FaceAuth에 접근하기 위한 QueryString

​1단계 — 암호화할 평문(JSON) 준비

​2단계 — FaceAuth 프로젝트 API 키로 AES-256 암호화 후 URL 조립

​요청 파라미터들에 대한 정의

Face Auth URL 검증 및 에러 처리

​FaceAuth API 엔드포인트

POST/FaceAuth

GET/FaceAuth

GET/FaceAuth/Image

DELETE/FaceAuth

​웹훅

Faceauth

Token ID 만료

FaceAuth 진행 방식 — 2가지 선택지

FaceAuth에 접근하기 위한 QueryString

1단계 — 암호화할 평문(JSON) 준비

2단계 — FaceAuth 프로젝트 API 키로 AES-256 암호화 후 URL 조립

요청 파라미터들에 대한 정의

FaceAuth API 엔드포인트

웹훅