[Qypher]Qypher 도입 방법

Qypher을(를) 자신의 사이트에서 사용해 봅시다

사용하는 기기에 따라 클릭 대신 탭해야 할 수도 있습니다.

현재 PHP로 작성된 프로그램이 공개되어 있습니다

* php 버전은 Ver.7.4 이상이 필요하며, Ver.8.3 이상을 권장합니다.

Qypher을(를) 도입하시려면 아래 사항이 가능한지 확인해 주세요

https 접근으로 응답할 수 있어야 합니다 (http://는 허용되지 않습니다)

Qypher API는 내부적으로 통신 내용을 암호화하지만, 추가적인 보안을 위해 https 통신이 가능한 환경에서만 제공됩니다.

OpenSSL을 사용할 수 있습니다

Qypher API는 OpenSSL 암호화 라이브러리를 사용합니다.

script 태그를 자유롭게 삽입할 수 있어야 합니다

Qypher API는 표시, QR 코드 분석 및 Qypher 본체와의 통신에 JavaScript를 사용합니다.

외부 도메인과 fetch() 통신이 가능해야 합니다

Qypher API는 분석한 데이터를 외부 도메인(https://qypher.be-on.biz)의 Qypher에 전송하고, Qypher 데이터와照合した 결과를 수신합니다.

input type="file" 및 canvas 요소로 DOM 조작을 사용할 수 있어야 합니다

Qypher API는 Qypher 카드 업로드, QR 코드 분석, 버튼 조작 등에 DOM 조작을 사용합니다.

HTML 내에 독자적인 요소를 삽입할 수 있어야 합니다

Qypher API는 로그인 전후의 HTML에 독자 요소를 삽입합니다.

서버 사이드(PHP 등)를 설치하고 실행할 수 있어야 합니다

Qypher API는 비밀키가 포함된 PHP 파일 설치가 필요합니다. 이 파일은 Qypher과의 통신 암호화 및 복호화, 일회용 키 확인 등 중요한 역할을 담당합니다.

위의 사항을 확인하셨다면 설정으로 진행합시다.

먼저 Qypher에 로그인하세요.
* 로그인 방법은 “Qypher 사용 방법”에 설명되어 있습니다.

개인 정보의 Qypher 연동, 연동 정보을(를) 클릭합니다.

도입 웹사이트 이름 :

Qypher을(를) 도입할 웹사이트의 공식 명칭을 입력하세요.

홈페이지의 웹 주소 :

웹사이트의 랜딩 페이지나 인덱스 페이지 주소를 https부터 입력하세요.

샌드박스 :

“샌드박스”을(를) 선택하는 동안에는 본 환경의 로그인 화면에 “조정 중”이 표시되며 로그인할 수 없습니다. 다양한 테스트가 완료되면 “운영 환경”을(를) 선택하고 “업데이트”을(를) 클릭하세요.

등록자 수 :

이는 Qypher을(를) 통해 등록된 웹사이트에 로그인한 사용자 수입니다. 동일 사용자가 여러 번 로그인해도 한 번만 카운트됩니다.

보호자 동의가 필요한 나이 :

보호자 확인이 필요한 연령을 설정합니다. 필요하지 않으면 “제한 없음”을(를) 선택하세요.

열람 가능한 나이 :

연령 제한이 있는 웹사이트의 경우 연령을 설정하세요. 필요하지 않으면 “제한 없음”을(를) 선택하세요.

사용 언어 :

앞으로 Qypher을(를) 도입한 웹사이트 목록이 작성되면, 사용 가능한 언어별 항목이 제공될 예정입니다. 그러나 브라우저 자동 번역 기능이 계속 발전한다면, 이 항목은 불필요해질 수도 있습니다.

획득 희망 데이터 :

Qypher에서 가져오고자 하는 사용자 데이터를 선택하세요. 가져올 수 있는 데이터는 이용 중인 요금제에 따라 달라집니다. “플랜 목록”을(를) 확인하세요.

이용 약관의 웹 주소 :

이용 약관의 URL을 https부터 입력하세요.

개인정보 처리방침의 웹 주소 :

개인정보 처리방침의 URL을 https부터 입력하세요.

로그인 후의 웹 주소 :

로그인 후 표시할 페이지 주소를 샌드박스용과 운영 환경용 모두 https로 시작하여 입력하세요.

웹훅의 웹 주소 :

웹훅 정보를 받을 URL을 샌드박스용과 운영 환경용 모두 https로 시작하여 입력하세요. 사용하지 않는 경우 빈칸으로 두셔도 됩니다. 웹후크는 Pro 플랜 이상에서 이용할 수 있습니다.

API 비밀 키를 저장할 폴더 :

「API 세트를 ZIP으로 다운로드」을 클릭하면 Qypher이(가) 「비밀 키 파일」을(를) 생성합니다. 이 「비밀 키 파일」이(가) 설치될 폴더를 https부터 입력하세요.

API 비밀키의 언어 종류 :

현재는 PHP만 제공되지만, 다른 언어도 지원할 예정입니다. 그때는 여기에서 원하는 언어를 선택하실 수 있습니다.

이용 요금제 :

이용할 플랜을 선택해 주세요. 자세한 내용은 플랜 목록를 읽어 주세요.

로그인 페이지, API 비밀 키, 이용 약관, 개인정보 처리방침, 웹훅, 로그인 후 페이지는 동일한 도메인 내에, 서브도메인을 사용하는 경우 동일한 서브도메인 내에 배치해 주세요.

Pro 플랜 이상에서 여러 웹사이트를 도입한 경우 “API 세트를 ZIP으로 다운로드”의 선택 목록에서 편집할 웹사이트를 선택하세요.

설정을 마쳤다면 다운로드합시다.

「API 세트를 ZIP으로 다운로드」을(를) 클릭하면 “QypherAPIset_(웹사이트명).zip”라는 압축 파일이 다운로드 폴더에 저장됩니다. 해당 파일을 더블 클릭하거나 유사한 방법으로 압축을 해제(열기)하세요.

파일 구성

QypherAPIset_(웹사이트 이름)/

├─ apiScript.txt ← 로그인 페이지의 원하는 위치에 이 내용을 복사하여 붙여넣어 주세요.

├─ 50자 이상 무작위 영숫자로 된 공개 키(1).php ← 비밀 키 처리를 위한 PHP 파일 (이하 "비밀키 파일"이라 합니다.)

├─ getData.php ← 로그인 후 표시되는 페이지에 이 내용을 복사해서 붙여넣어 주세요.

├─ README.txt ← 사용 설명서

└─ Sandbox/

├─ Sandbox_apiScript.txt ← ( 샌드박스용 ) 로그인 페이지의 원하는 위치에 이 내용을 복사하여 붙여넣어 주세요.

├─ Sandbox_50자 이상 무작위 영숫자로 된 공개 키(2).php ← ( 샌드박스용 ) 비밀 키 파일

├─ Sandbox_getData.php ← ( 샌드박스용 ) 로그인 후 표시되는 페이지에 이 내용을 복사해서 붙여넣어 주세요.

├─ nine.jpg ← 샌드박스용 9세의 Qypher 카드 테스트 사용자 (보호자의 승인이 필요한 동작을 확인할 수 있습니다.)

├─ eleven.jpg ← 샌드박스용 11세의 Qypher 카드 테스트 사용자 (보호자 승인이 필요한 나이 경계를 확인할 수 있습니다.)

├─ thirty.jpg ← 샌드박스용 30세의 Qypher 카드 테스트 사용자 (성인으로 정상 로그인할 수 있습니다.)

└─ guardian.jpg ← 샌드박스용 Qypher 카드 테스트 사용자 (9세와 11세 아동의 보호자) (보호자 승인 절차를 테스트하는 데 사용할 수 있습니다.)

샌드박스에서 시도해 봅시다

샌드박스에서는 Qypher 로그인과 관련된 다양한 실험과 체험을 할 수 있습니다.

샌드박스에서 로그인하면 모든 동작은 샌드박스 내에서만 이루어지며 운영 환경에는 반영되지 않습니다.

샌드박스 내 이메일은 샌드박스를 사용하는 사용자에게만 전송됩니다.

Sandbox_apiScript.txt의 모든 내용을 복사하여 샌드박스용 로그인 페이지의 원하는 위치에 붙여넣으세요.

<input type="hidden" id="QypherAnyKey" value="">의 value 속성에 전달할 데이터를 넣으면 로그인 후 해당 데이터를 넘겨받을 수 있습니다.
( 입력한 내용에 HTML 태그, JavaScript 코드, 파일 경로 등이 포함된 경우 자동으로 무효화됩니다. 유해한 value가 감지되면 Qypher 사용이 제한될 수 있습니다. )

Qypher연동 정보의 API 비밀 키를 저장할 폴더에 설정한 위치에 샌드박스용 비밀 키 파일 파일을 배치해 주세요.
운영 환경용과 같은 위치에 설치해 주세요.

이 파일은 절대로 수정하지 마세요. 변조된 경우 Qypher 본체의 검증에서 무효 처리되어 로그인 요청이 거부될 수 있습니다.
파일 이름을 변경하지 마세요. Qypher에서 인식할 수 없게 됩니다.

업로드 후, 파일 권한이 올바르게 설정되었는지 확인해 주세요.

권장 604 또는 644
*Windows 서버를 사용하는 경우 위의 “604 / 644” 권한 설정은 필요하지 않지만, 파일이 웹 서버(IIS 등)에서 읽을 수 있도록 적절한 권한을 부여해 주세요.

Sandbox_getData.txt의 모든 내용을 복사하여 샌드박스용 로그인 후 페이지의 기본 틀로 사용하세요.

if($Qypher["success"]){} 에는 로그인 성공 후의 내용을, else{} 에는 로그인 실패 시의 내용을 입력하세요.
로그인에 성공했을 때의 기본값에는 “이 페이지를 새로 고치면 다시 로그인해야 합니다.”가 포함되어 있습니다.

비밀 키 파일를 호출하여 해당 데이터를 복호화하는 PHP 프로그램이 로그인 후 페이지에 붙여넣어져 있습니다.

이때 암호화된 로그인 시간은 일회용 비밀번호로 검증됩니다. 이 시각이 5초 이상 차이날 경우 로그인이 거부됩니다.

이는 사용자가 로그아웃한 후 다른 사람이 로그인 페이지로 돌아가 새로고침하여 로그인이 되어 버리는 것을 방지하기 위한 중요한 조치입니다.

비밀 키 파일 내부를 변경하면 보안상의 취약점이 생길 수 있으므로 어떤 경우에도 변경하지 마세요.

Qypher에서 사용자 데이터를 가져옵시다

$Qypher 배열에서 가져올 수 있습니다.

$Qypher["success"] ← true = 로그인 성공, false = 로그인 실패
$Qypher["uuid"] ← 로그인 기록용 Qypher 식별자 ( Qypher에 문의할 때 사용하세요 )
$Qypher["Qypher_ID"] ← 사용자의 고유 번호 ( 어떤 사용자가 로그인했는지 식별하는 데 사용하세요 )
$Qypher["login_time(UTC)"] ← YYYY-MM-DDThh:ii:ssZ ( 로그인한 시간은 UTC 기준으로 확인 가능합니다 )
$Qypher["meetsAgeReq"] ← '사이트가 정한 연령 조건을 충족하는지'의 결과(1=충족 / 0=미충족). 로그인 성공 시 기본 1. 실제 나이나 생년월일 자체는 전달되지 않습니다.
$Qypher["ageReq"] ← 그 사이트가 설정한 연령 기준값(0=없음)
$Qypher["guardianApproved"] ← 이용자의 실제 나이가 보호자 확인 기준값 미만인지 — needGuardian 값(미설정 시 13세. 13세 미만은 설정값과 무관하게 항상 적용)(1/0). Qypher는 보호자 동의 없이는 로그인을 완료하지 않으므로, 1은 그 동의를 받아 로그인한 어린 이용자를 의미합니다
$Qypher["under10"] ← 10세 미만인지에 대한 대략적인 플래그(1/0). 어린이용 표시·문구로 전환할 때 사용합니다. 실제 나이나 생년월일은 전달되지 않으며, 10세 경계에서 한 번만 바뀌므로 반복 로그인해도 생일을 알아낼 수 없습니다.
$Qypher["under13"] ← 13세 미만인지에 대한 대략적인 플래그(1/0). under10과 마찬가지로 실제 나이를 받지 않고 연령대로 표시를 전환하기 위한 것입니다. 13세 경계에서 한 번만 바뀝니다.
$Qypher["QypherAnyKey"] ← 로그인 페이지에서 전달하고 싶은 데이터 ( apiScript.txt 내 id="QypherAnyKey"의 value 속성에 입력한 데이터입니다. )
$Qypher["json"] ← 모든 데이터의 JSON 형식 ( JavaScript 처리 등에 활용하세요 )

기본 설정으로 Qypher가 제공하는 데이터는 위 항목들입니다.Qypher연동 정보의 획득 희망 데이터에서 항목에 체크하면 전달되는 데이터가 늘어납니다. 단, 사용자가 허용하지 않았거나 등록하지 않은 데이터는 비어 있습니다.

$Qypher["surname"] ← 성
$Qypher["givenName"] ← 이름
$Qypher["nickname"] ← 닉네임
$Qypher["email"] ← 이메일 주소
$Qypher["birthday"] ← 생년월일
$Qypher["postalCode"] ← 우편번호
$Qypher["country"] ← 국가 / 지역
$Qypher["area1"] ← 주 / 도
$Qypher["area2"] ← 시 / 군 / 구
$Qypher["address"] ← 도로명 및 번지
$Qypher["building"] ← 건물명
$Qypher["room"] ← 방 이름

예: echo `{$Qypher["surname"]} {$Qypher["givenName"]} 님, Qypher에 오신 것을 환영합니다.`;

개인 정보를 취급할 때 각별히 주의하시기 바랍니다.

운영 환경 준비를 합시다

운영 환경에서는 샌드박스에서 사용하는 공개 키와 비밀 키가 다릅니다. 샌드박스의 내용을 그대로 복제해도 운영 환경는 작동하지 않습니다.

샌드박스와 동일한 절차로 운영 환경를 설정합니다.

apiScript.txt의 모든 내용을 복사하여 운영 환경용 로그인 페이지의 원하는 위치에 붙여넣으세요.

Qypher연동 정보의 API 비밀 키를 저장할 폴더에 설정한 위치에 운영 환경용 비밀 키 파일 파일을 배치해 주세요.
샌드박스용과 같은 위치에 설치해 주세요.

업로드 후, 파일 권한이 올바르게 설정되었는지 확인해 주세요.

getData.txt의 모든 내용을 복사하여 운영 환경용 로그인 후 페이지의 기본 틀로 사용하세요.

Qypher에 로그인하여 Qypher 연동 정보의 샌드박스를 운영 환경으로 설정하고 업데이트를 클릭하세요.

로그인 페이지에 “설치 위치를 확인 중입니다”가 표시되는 경우 샌드박스용을 사용하지 않았는지 확인하시고, 여러 페이지에서 Qypher을 사용 중이라면 해당 웹사이트에 맞는 것을 사용하고 있는지 확인하세요.

웹훅을 사용하여 정보를 확실하게 하세요.

Pro 요금제 이상에서 웹훅을 이용할 수 있습니다. 사용자가 로그인한 후 정보를 제대로 처리하지 못한 경우 웹훅을 활용하세요.

Pro 요금제 이상 사용자가 API를 다운로드하면 폴더에 webhook.php와 Sandbox_webhook.php 두 개의 파일이 들어 있습니다. 있는 그대로 여기에 필요한 내용을 추가하여 사용하세요.

데이터 가져오기는 로그인 후 페이지에서 사용하는 방법과 동일합니다.

파일을 설치한 위치를 Qypher 연동 정보의 웹훅에 https부터 입력하고 업데이트을 클릭하세요.

웹훅을 사용하지 않는 경우 Qypher 연동 정보의 웹훅를 비워 두고 업데이트을 클릭하세요.

로그인 혁명. Qypher를 통한 QR만으로 스마트 인증.

로그인 혁명.
Qypher를 통한 QR만으로 스마트 인증.