> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FACE AUTH 가이드

> 기존 eKYC 승인자의 셀피와 비교하여 동일인 여부를 확인하는 FACE AUTH 애드온 서비스 사용 방법을 안내합니다.

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

## 대표 활용 시나리오

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

<CardGroup cols={2}>
  <Card title="단말기 변경" icon="mobile-screen">
    **금융기관**에서 기기 변경·번호 변경 시 계정 도용 위험을 낮추기 위한 재인증 수단으로 사용합니다.
  </Card>

  <Card title="이상징후 감지 시 재인증" icon="shield-exclamation">
    **ATO 방지** - 고위험 로그인, 해외 접속, 대량 시도 탐지 시 추가 얼굴 인증으로 접근 차단/해제 정책을 적용합니다.
  </Card>

  <Card title="정기 본인 재확인" icon="calendar-check">
    **주기적 KYC Refresh** - 고가치 서비스·규제 산업에서 주기적 동일인 확인 절차로 활용합니다.
  </Card>

  <Card title="비밀번호 분실/정보 변경" icon="key">
    비밀번호 재설정, 결제수단·연락처 변경 등 중요 계정 변경 전 본인 확인 단계로 삽입합니다.
  </Card>
</CardGroup>

## 동작 방식 (3-Step)

<Steps>
  <Step title="전제조건">
    eKYC의 **승인된 Submission**이 존재해야 합니다. (Reference)
  </Step>

  <Step title="진행">
    Add-On URL 호출 (pid + Submission ID 포함) → 셀피 촬영

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

  <Step title="판정/저장">
    등록본 vs 검증본 자동 비교 → 결과는 **Auth ID**(제출건)로 대시보드에 저장됩니다.
  </Step>
</Steps>

<Warning>
  **핵심 체크**

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

## FACE AUTH의 장점

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

***

## 프로젝트 생성 및 설정

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

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

대시보드의 \*\*애드온 메뉴 → '프로젝트 생성하기'\*\*를 선택해 새 FACE AUTH 프로젝트를 만듭니다.

생성 즉시 eKYC 프로젝트와 종속 연결이 형성되며, Add-On URL과 API 키가 자동 매핑됩니다.

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

<Frame caption="프로젝트 생성 전 화면">
  <img src="https://mintcdn.com/argosidentity/352WpTnZFyEfW7I6/images/dashboard/new/addon-setting/addon-create.png?fit=max&auto=format&n=352WpTnZFyEfW7I6&q=85&s=be7dcab4be72d564a12bd179d2d289c0" alt="Add-On 프로젝트 생성 화면" width="1853" height="564" data-path="images/dashboard/new/addon-setting/addon-create.png" />
</Frame>

<Frame caption="프로젝트 생성 이후 화면">
  <img src="https://mintcdn.com/argosidentity/352WpTnZFyEfW7I6/images/dashboard/new/addon-setting/project_made.png?fit=max&auto=format&n=352WpTnZFyEfW7I6&q=85&s=87ec5bab371770b41e2ab9aafbb18bf9" alt="Add-On 프로젝트 생성 화면" width="1876" height="217" data-path="images/dashboard/new/addon-setting/project_made.png" />
</Frame>

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

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

<Frame caption="프로젝트 정보 설정 화면">
  <img src="https://mintcdn.com/argosidentity/352WpTnZFyEfW7I6/images/dashboard/new/addon-setting/project-setting.png?fit=max&auto=format&n=352WpTnZFyEfW7I6&q=85&s=e84daae58c03d1f6af172973c9be29c3" alt="Add-On 프로젝트 생성 화면" width="1853" height="359" data-path="images/dashboard/new/addon-setting/project-setting.png" />
</Frame>

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

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

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

<Frame caption="프로젝트 정책 설정 화면">
  <img src="https://mintcdn.com/argosidentity/352WpTnZFyEfW7I6/images/dashboard/new/addon-setting/project-threshold-set.png?fit=max&auto=format&n=352WpTnZFyEfW7I6&q=85&s=b3f4108eaf1409b356094b71ff0fb109" alt="Add-On 프로젝트 생성 화면" width="1859" height="428" data-path="images/dashboard/new/addon-setting/project-threshold-set.png" />
</Frame>

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

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

**특수 환경 옵션:**

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

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

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

**필수 파라미터:**

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

**URL 패턴 예시:**

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

<Tip>
  `encrypted` 문장에서 Submission ID는 `sid`, Token ID는 `token`으로 표시해서 사용합니다.
</Tip>

#### 토큰 만료 조건 설정

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

<Frame caption="프로젝트 토큰 설정 화면">
  <img src="https://mintcdn.com/argosidentity/352WpTnZFyEfW7I6/images/dashboard/new/addon-setting/project-token-expiration.png?fit=max&auto=format&n=352WpTnZFyEfW7I6&q=85&s=28056b8da1ad1c439b10eafa403d8d93" alt="Add-On 프로젝트 생성 화면" width="1859" height="472" data-path="images/dashboard/new/addon-setting/project-token-expiration.png" />
</Frame>

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

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

***

## 사용자에게 제공하기

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

<Tabs>
  <Tab title="A. Add-On URL (권장)">
    사용자에게 Add-On URL을 열도록 안내하면 웹 화면에서 셀피 촬영으로 재인증을 진행합니다.

    **필수 파라미터:**

    * `pid={AddOn Project ID}` — URL 쿼리스트링에 평문으로 포함
    * `encrypted={...}` — 내부에 `sid={승인된 eKYC Submission ID}` 포함, AES-256으로 암호화 필수 ([Step 4](#step-4-add-on-url-파라미터-및-암호화-설정) 참고)

    ```text URL 패턴 theme={null}
    https://form.argosidentity.com/face-auth?pid={ADDON_PID}&encrypted={encrypted}
    ```

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

    <Check>
      **체크리스트**

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

  <Tab title="B. API 기반 연동">
    자체 UI에서 버튼·모달·단계형 플로우로 FACE AUTH를 노출하고, 백엔드에서 Add-On을 API 기반으로 호출합니다.

    <Warning>
      API 방식으로 진행 시 **Active Liveness가 지원되지 않습니다**.

      * faceImage 권장 사양: 960 x 720
      * 기존 liveform API Key와는 다른 **별도의 API Key**가 필요합니다.
    </Warning>

    <Check>
      **체크리스트**

      * ✅ eKYC 승인 이력(등록본)과 연계되는 Add-On 프로젝트 생성 확인
      * ✅ 호출 시 pid·submissionId 전달 로직 구현
      * ✅ 성공/실패 콜백에서 다음 단계로 라우팅
    </Check>

    <Card title="POST/Face Auth API 문서" icon="code" href="/ko/idcheck/add-on/post-faceauth">
      API 기반 연동 방법을 자세히 확인하세요.
    </Card>
  </Tab>
</Tabs>

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

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

<Frame caption="정상 인증 화면 및 sid를 잘못 사용한 경우 나타나는 오류 화면">
  <img src="https://mintcdn.com/argosidentity/9nmfC9DUN64YxjGL/images/dashboard/addon-setting/normal_error_page.png?fit=max&auto=format&n=9nmfC9DUN64YxjGL&q=85&s=27127ce3bd084f39782d53218e403389" alt="Add-On 프로젝트 생성 화면" width="1080" height="899" data-path="images/dashboard/addon-setting/normal_error_page.png" />
</Frame>

***

## AUTH ID - 인증 결과 확인

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

### 대시보드에서 결과 확인

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

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

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

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

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

<Frame caption="Add-On 프로젝트의 Auth ID 대시보드">
  <img src="https://mintcdn.com/argosidentity/352WpTnZFyEfW7I6/images/dashboard/new/addon-setting/auth_id_list.png?fit=max&auto=format&n=352WpTnZFyEfW7I6&q=85&s=d9760c65c611b52a3c18ced3022551fc" alt="Add-On 프로젝트의 Auth ID 대시보드" width="3718" height="1639" data-path="images/dashboard/new/addon-setting/auth_id_list.png" />
</Frame>

### Auth ID 상세 정보

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

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

<Frame caption="Add-On 프로젝트의 Auth ID 상세 화면">
  <img src="https://mintcdn.com/argosidentity/352WpTnZFyEfW7I6/images/dashboard/new/addon-setting/auth_id_detail.png?fit=max&auto=format&n=352WpTnZFyEfW7I6&q=85&s=52c8b5e2200719a6c63977312b408af6" alt="Add-On 프로젝트의 Auth ID 대시보드" width="1782" height="1288" data-path="images/dashboard/new/addon-setting/auth_id_detail.png" />
</Frame>

***

## 웹훅으로 실시간 연동

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

트리거 타입: `"faceAuth"`

```json theme={null}
{
  "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" }
    }
  }
}
```

<Check>
  **구현 체크리스트**

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

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

***

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

<Steps>
  <Step title="프로젝트 생성">
    대시보드 → 애드온에서 FACE AUTH 프로젝트를 생성합니다.
  </Step>

  <Step title="정책값 설정">
    얼굴 일치 임계값 / 라이브니스 / 가림 차단(ON/OFF)을 설정합니다.
  </Step>

  <Step title="eKYC 승인 Submission 확보">
    Reference로 사용할 승인된 eKYC Submission이 필요합니다.
  </Step>

  <Step title="호출 설계">
    Add-On URL에 pid + Submission ID 포함 (데스크톱→QR→모바일 흐름 고려)
  </Step>

  <Step title="결과 확인 루틴">
    대시보드에서 Auth ID(제출건) 상태·정책·비교 결과를 모니터링합니다.
  </Step>
</Steps>

### 운영 팁

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

***

## 관련 문서

<CardGroup cols={2}>
  <Card title="Add-On API 개요" icon="puzzle-piece" href="/ko/idcheck/add-on/overview">
    Add-On 서비스의 전체 개요를 확인합니다.
  </Card>

  <Card title="POST/Face Auth API" icon="code" href="/ko/idcheck/add-on/post-faceauth">
    API를 통한 FACE AUTH 연동 방법을 확인합니다.
  </Card>

  <Card title="FACE AUTH 웹훅" icon="webhook" href="/ko/idcheck/add-on/add-on-webhook">
    FACE AUTH 결과를 웹훅으로 수신하는 방법을 확인합니다.
  </Card>

  <Card title="암호화 가이드" icon="lock" href="/ko/idcheck/getting-started/encrypt-and-decrypt-data/overview">
    URL 암호화 방법을 확인합니다.
  </Card>
</CardGroup>