OmniID 바이오 등록과 확인의 핵심 흐름을 이해하고, 가맹점 서비스에 안전하게 연동하는 방법을 알아보세요.
먼저 전체 흐름과 꼭 필요한 작업을 살펴볼게요. API 필드와 오류 코드는 OmniID API, 가맹점 바이오 API, 상태 및 오류 처리에서 확인할 수 있어요. 실제 구현에 활용할 수 있는 코드는 가맹점 연동 예제를 참고해 주세요.
구조 이해하기#
가맹점은 Frontend, Backend, Bio API 세 부분을 연결하면 돼요.
| 구성요소 | 구현할 기능 |
|---|---|
| Frontend | Hosted UI를 열고 session_id로 결과 확인을 트리거해요. |
| Backend | 토큰을 발급하고 세션을 만든 뒤 결과를 조회해요. |
| Bio API | OmniID 서명을 검증하고 등록 데이터를 저장·조회해요. |
Hosted UI, QR·앱 연결, 바이오 매칭은 OmniID가 처리해요.
1. 연동 정보를 준비해요#
먼저 OmniID 운영팀에 아래 정보를 전달해 주세요.
- 가맹점명
- HTTPS 가맹점 바이오 API 주소
- 가맹점 콘솔 담당자 이름·이메일
정보를 전달하면 아래 값을 받을 수 있어요.
merchant_idclient_idclient_secret- 가맹점 콘솔 계정
환경별 접속 주소는 다음과 같아요.
| 환경 | OmniID API | Hosted UI | 가맹점 콘솔 |
|---|---|---|---|
| 테스트 | https://api.test.omniid.ai.kr | https://verify.test.omniid.ai.kr | https://merchant.test.omniid.ai.kr |
| 운영 | https://api.omniid.ai.kr | https://verify.omniid.ai.kr | https://merchant.omniid.ai.kr |
Backend에는 연동하려는 환경의 OmniID API 주소를 설정해 주세요. Hosted UI 주소는 직접 조립하지 말고 세션 생성 응답의 popup_url을 그대로 사용해야 해요. 테스트와 운영의 merchant_id, client_id, client_secret은 서로 호환되지 않으니 같은 환경의 값끼리 사용해 주세요.
2. Backend에서 세션을 만들어요#
Backend에서 OAuth access token을 발급받고, 필요한 세션을 만들어 주세요.
| 목적 | API |
|---|---|
| 바이오 등록 | POST /v1/enrollment-sessions |
| 바이오 확인 | POST /v1/verification-sessions |
세션을 만들면 session_id와 popup_url을 받아요.
session_id: 나중에 결과를 조회할 때 사용해요.popup_url: Frontend에서 Hosted UI를 열 때 사용해요.
바이오 확인 세션에는 등록 결과로 받은 result.finger가 필요해요.
PC popup 완료 신호의 target origin을 고정하려면 세션 생성 요청에 가맹점의 전체 URL인
return_url을 넣어 주세요. HTTPS URL만 허용되며 HTTP URL은 거부돼요. 이 값은 OmniID 운영팀에
제출하는 온보딩 정보가 아니며, 모바일 자동 복귀용 URL도 아니에요.
3. Frontend에서 Hosted UI를 열어요#
PC에서는 popup_url을 popup으로 열어 주세요. 모바일에서는 브라우저 정책에 따라 새 화면처럼 열리거나 현재 창에서 이동할 수 있어요. 어떤 방식이든 Hosted UI 주소를 직접 만들지 말고 응답으로 받은 값을 그대로 사용해 주세요.
PC popup에서는 Hosted UI가 postMessage로 완료 신호를 보낼 수 있어요. 모바일은 manual return이 기본이에요. 앱은 완료 후 URL을 새로 열지 않고 종료하거나 사용자가 원래 가맹점 화면으로 돌아가도록 안내해요. 따라서 Frontend는 세션 생성 응답의 session_id를 보관하고 polling, 앱 복귀(focus/visibilitychange/pageshow), 사용자의 결과 확인 동작으로 Backend 결과 조회를 트리거해야 해요.
4. Backend에서 결과를 확인해요#
Frontend가 PC popup 완료 신호를 받거나, 모바일 앱에서 수동으로 돌아오거나, polling 주기가 되면 Backend에 결과 확인을 요청해요.
GET /v1/sessions/{session_id}/result?merchant_user_ref={user_ref}
5. Bio API를 구현해요#
OmniID가 등록 데이터를 저장하고 불러올 수 있도록 API 두 개를 구현해 주세요.
| API | 역할 |
|---|---|
POST /enrollments | 등록 데이터를 저장해요. |
POST /enrollments/lookup | 등록 데이터를 조회해요. |
Bio API는 요청을 처리하기 전에 OmniID의 Ed25519 서명을 검증해야 해요.
- raw request body를 보존해요.
X-OmniID-Key-Id에 맞는 공개키를 조회해요.- merchant id, timestamp, nonce를 검사해요.
- body hash와 Ed25519 서명을 검증해요.
- 검증에 성공한 요청만 저장하거나 조회해요.
전체 검증 순서는 가맹점 바이오 API - Verification Rules를 따라 주세요.
등록과 확인은 이렇게 달라요#
등록에 성공하면 result.finger를 사용자와 연결해 저장해 주세요. 바이오 확인 세션을 만들 때 이 값을 다시 전달해요.
결과를 확인해요#
| 결과 | 의미 | 처리 방법 |
|---|---|---|
succeeded + 등록 | 등록이 끝났어요. | result.finger를 저장해요. |
succeeded + matched=true | 바이오가 일치해요. | 인증 성공으로 처리해요. |
succeeded + matched=false | 바이오가 일치하지 않아요. | 재시도나 대체 인증을 안내해요. |
failed | 처리 중 문제가 생겼어요. | failure_code를 확인해요. |
expired | 세션이 만료됐어요. | 새 세션을 만들어요. |
canceled | 사용자가 취소했어요. | 시작 화면으로 돌아가요. |
matched=false는 시스템 오류가 아니에요. 매칭은 정상적으로 끝났지만 바이오가 일치하지 않은 상태예요.
created, opened, app_launched, callback_received, processing은 아직 진행 중인 상태예요. 잠시 후 결과를 다시 조회해 주세요.
이것만은 꼭 지켜 주세요#
client_secret과 access token은 Backend에서만 사용해요.- 최종 성공 여부는 Backend의 결과 조회로 확정해요.
- 세션을 만들 때
Idempotency-Key를 사용해요. - timeout으로 같은 요청을 다시 보낼 때는 같은 멱등 키와 body를 사용해요.
- Bio API는 raw body를 기준으로 OmniID 서명을 검증해요.
- 바이오 등록 데이터는 가맹점 저장소에만 보관하고 로그에 남기지 않아요.
- 모바일에서는 앱이 URL을 열어주지 않아도, 원래 가맹점 화면으로 돌아왔을 때
session_id로 결과를 다시 조회해요.
연동을 테스트해요#
- 등록 후
result.finger가 저장돼요. - 저장한
finger로 확인 세션을 만들 수 있어요. - 일치와 불일치가 서로 다른 결과로 처리돼요.
- popup을 먼저 닫아도 Backend가 실제 결과를 조회해요.
- 모바일에서 앱이 종료되어 가맹점 화면으로 수동 복귀해도 Backend가 실제 결과를 조회해요.
- 같은 멱등 키로 재시도해도 데이터가 중복되지 않아요.
- 변조된 body, 만료된 timestamp, 재사용 nonce가 Bio API에서 거부돼요.
- 만료된 세션은 새 세션으로 다시 시작해요.
운영 전 협의해요#
파일럿 시작 전 OmniID 담당자와 세션 생성·결과 조회 API의 적용 한도, OmniID 세션·결과
데이터 보관 기간, 지원 문의 채널, E2E 검수 시나리오를 확인해 주세요. 현재 test/production
설정에서 OAuth token endpoint는 client_id별 60초에 30회로 제한됩니다. access token은 기본
10분 동안 유효하므로 만료 전까지 캐시해 사용해 주세요.
더 자세히 알아봐요#
- 가맹점 연동 예제: Backend, Frontend, Bio API 전체 코드
- OmniID API: 인증, 세션 생성, 결과 조회 스펙
- 가맹점 바이오 API: 저장·조회 API와 서명 검증
- 상태 및 오류 처리: 세션 상태, 오류, 재시도 기준