이용기관 연동 가이드 (VeraOTK v1.0)

1. 개요

VeraOTK 서비스는 서버에 비밀번호 정보를 남기지 않고, ‘종단 간 암호화(End-to-End ecvryption)’ 기술을 이용, 개인정보가 유출되지 않도록 설계되었고, 비밀번호가 피싱이나 해킹 공격에서 보호될 수 있는 강력한 차세대 미래 보안 솔루션입니다.

VeraOTK 서비스의 핵심가치입니다.

ㆍ한번의 키 등록으로 다중 디바이스 공유하여 빠르고 간편한 인증 기능을 제공
ㆍ뱅킹, 모바일 결제등 광범위한 확장성을 제공
ㆍ해킹과 피싱 방지에 강력한 보안기능을 제공
ㆍ재발급 및 인증기기 구입에 필요한 비용절감 효과 탁월

2. 주요 특징

가. MFA (Multi Factor Authenticator)

ㆍ기존 OTP를 대체하는 차세대 OTP 기술, OTK(One Time Keys)
ㆍ비용, 보안성, 호환성, 편의성이 강화된 MFA

나. Anti-Phishing (End-to-End Authentication 기술)

ㆍ웹사이트 도메인별로 종속적인 패스키를 등록하여 사용이 가능한 구조로, 위조된 사이트에는 패스키 사용 자체가 불가능하여 SMS, OTP 와 같이 추측, 재사용, 해독 ,가로채기 공격등이 불가능합니다.

다. Cross Device Key Binding

ㆍIOS, Android 플랫폼을 활용한 디바이스간 Key 자동 동기화
ㆍiCloud 암호 및 키체인 혹은 Google Account를 통해 해당 계정이 사용되는 디바이스에 Passkey 자동 동기화 적용

3. 기능 구성

4. 패스키 API 이용 절차

ㆍ이용기관의 사용자는 패스키 사용을 위해 ‘등록’ 혹은 ‘인증’과 같은 서비스를 요청하고, 그 결과에 따라 이후 로직을 수행하게 됩니다.
ㆍ사용자의 패스키 서비스 요청(API)에 대한 최종 결과는 이용기관 서비스 서버(ex, 인증 서버)가 사용자로부터 전달받은 callbackURL의 파라미터 정보인 서비스, 트랜잭션, 식별정보를 패스키 서버로 요청함으로써 해당 서비스의 처리 결과를 알 수 있습니다.
ㆍ이에 이용기관 서버(ex, 인증서버)가 패스키 서버로 서비스 트랜잭션 결과를 조회하는 요청 및 응답에 관련된 내용을 기술합니다.

4.1. 사용자 등록 및 검증

ㆍ패스키를 서버에 등록 및 이용하려면 먼저 패스키 서버에 사용자 등록을 합니다.
ㆍ패스키 서버에 사용자를 등록하려면 이메일로 발송된 일회용 인증코드를 입력 받는 절차를 사용하여 이메일의 실체 여부를 검증받아야 합니다.
ㆍ이메일 검증 절차는 checkUser(), verifyAuthCode() 함수를 통하여 처리됩니다

4.2. 사용자 이메일 재확인

사용자 재인증 절차등 필요에 의해서 등록된 사용자의 이메일을 재검증할 경우 requestAuthCode() 함수를 사용합니다.

4.3. 패스키 생성 및 등록

패스키를 통하여 서비스 서버에 인증을 하기위해 우선 패스키를 서버에 등록하여야 합니다.
새로운 패스키를 생성 및 서버에 등록하기 위해서는 register() 함수를 통하여 진행합니다.

4.4. 패스키 인증 및 검증

서비스 서버에 인증을 하려면 등록된 패스키를 사용하여 전자서명 값을 생성하고 그것을 패스키 서버로부터 검증받아야 합니다.
패스키 생성 및 검증은 assertion() 함수를 사용합니다.

4.5. callbackURL 통한 등록/인증 처리 (서비스 서버)

ㆍ패스키 등록이나 인증절차는 패스키 서버에서 관리되고, 실제 서비스 서버 및 서비스 서버의 사용자 인증 데이터베이스와는 별도로 처리됩니다.
ㆍ그러므로 패스키 서버를 통하여 등록 및 인증이 완료되면, 처리 결과를 서비스 서버로 전달하여 실제 서비스 서버의 사용자 정보와 동기화 절차가 필요합니다.
ㆍ패스키 서비스 신청시 callbackURL을 등록해 놓으면, 그 callbackURL을 통하여 패스키 처리 결과를 조회할 수 있는 파라미터가 전달됩니다.
ㆍregister()나 assertion() 함수 호출이 성공하면 처리결과에 callbackURL이 반환됩니다. (반환된 URL은 서비스 서버에 설치됨)
ㆍ반환된URL을 호출하여 서비스 서버에서 패스키 서버로 처리 결과를 조회한 후 서비스 서버의 사용자 정보와 동기화합니다.

등록된 calbackURL이 https:// service-domain.com/callback.jsp 이면, 리턴되는 callbackURL은 https://you-service-domain.com/callback.jsp?type=1&svcTxId=4kmlgdr과 같이 호출됩니다.
type
ㆍ1 : 패스키 등록을 하기 위하여 register()를 사용한 경우
ㆍ2 : 패스키 인증을 위하여 assertion()을 사용한 경우
svcTxId
ㆍ패스키 서버에 서비스 처리 결과를 조회할때 사용하는 트랜잭션 식별정보

4.6. QR 코드 이용

ㆍoptions.qrTokenClassifier() 함수를 사용하여 QR토큰을 사용가능 장치로 판단되면, register() 호출시 패스키 인증자(Authenticator) 사용 API를 호출하는 대신, 자동으로 QR토큰이 발급되며, options.qrCodeHandler()가 호출됩니다.
ㆍ발급된 QR토큰이 처리되거나 취소 또는 만료 될때까지 QR토큰을 검사하며, 처리가 완료되면 register()나 assertion()호출의 결과로 반환됩니다.

4.7. QR 코드 진행 취소

ㆍQR토큰이 생성되어 QR코드가 표시되면, QR토큰이 만료(정상처리/취소/오류)될 때까지 options.qrTokenCheckInterval 설정 주기마다 자동으로 QR토큰 상태를 확인합니다.
ㆍ이때 사용자가 직접 취소할 수 있는 수단을 제공하고자 한다면, cancelQRToken()을 사용할 수 있습니다.

※ cancelQRToken() 사용시 주의사항
ㆍqrToken을 직접 넘겨줄 수 없습니다.
ㆍ취소처리 호출이 가능한 곳은 QR코드를 표시한 장치와 QR코드를 통하여 구동된 장치 두곳 뿐입니다.
ㆍQR코드를 띄운 장치는 이미 QR코드를 생성하기 위해서 내부에 qrToken을 가지고 있으므로 외부에서 넘겨줄 필요가 없습니다.
ㆍQR코드를 통하여 구동된 장치는 qrToken를 통하여 호출된 URL이므로 client가 이미 qrToken을 보유중이므로 명시적으로 qrToken을 직접 넘겨줘야 할 일은 불필요합니다.

5. 패스키 서비스 가용범위

6. 서비스 이용 절차

절차	역할
관리자 가입 등록 및 고객사 정보 등록 신청	이용기관 (관리자)
등록처리	위즈베라
서비스 승인 확인 메일 발송	위즈베라
서비스 승인 확인 메일 수신	이용기관 (관리자)
개발 가이드 및 패스키 서비스 QnA 전달 클라이언트 및 서버 개발코드 적용	이용기관 (개발자)
패스키 서비스 테스트, 인증화면 접속 및 서비스 호출	이용기관 (개발자)
인증화면 접속	사용자 (테스터)
패스키 클라이언트 모듈 전송	패스키 서버
서비스 API 호출	이용기관 인증앱
서비스 API 응답	패스키 서버
API 결과 정보 요청	이용기관 (서버)
API 결과 정보 응답	패스키 서버
결과처리 반환	이용기관 (서버)
서비스 호출 결과 반환	이용기관 인증앱

6.1. 서비스 신청화면 접속하기

6.2. 서비스 신청하기

7. 사전 준비 사항

가. 위즈베라와 계약을 통해 이용기관 정보를 신청 및 등록 후 접근토큰 요청을 위한“이용기관 액세스키” 및 주요정보 암호화를 위한“암호키” 를 발급받아야 합니다.

나. API 연계를 위해 필요한 정보를 신청합니다.
ㆍ서비스 도메인 주소
ㆍ담당자 전자메일 주소
ㆍ이용기관 서비스 서버 IP 주소
ㆍ인증결과 수신할 앱스키마 주소 (인증결과 수신을 위한 callback url)

다. 신청 완료 후 아래의 값을 등록메일로 수신 및 확인합니다.
ㆍ클라이언트 아이디 (client_id)
ㆍ액세스키 아이디 (access_key_id)
ㆍ액세스키 (access_key)

라. 방화벽 설정

구분	Domain	Host	Port
개발	svc.passkeys.kr	223.130.136.75	443
운영	svc.passkeys.kr	223.130.136.75	443

마. 각 기능별 이용기관에 제공하는 정보

구분	제공정보
userHandle	사용자 식별자값
txType	1 : 패스키 등록을 하기 위하여 register()를 사용한 경우 2 : 패스키 인증을 위하여 assertion()을 사용한 경우