앱 연동
앱을 등록하고, 호스팅 OpenID Connect 페이지로 사용자를 로그인시키거나 서명된 서버 API를 호출합니다.
앱을 Yeap Verify에 연결하는 방법은 두 가지입니다.
| 방법 | 적합한 경우 |
|---|---|
| 호스팅 로그인 페이지(OpenID Connect) | 이미 OpenID Connect를 지원하는 앱. Verify가 숫자를 표시하고 승인을 기다리며, 앱은 ID 토큰을 받습니다 |
| 서버 API | 두 번째 단계(푸시, TOTP, 백업 코드)를 직접 구현하는 앱 |
두 방법 모두 팀 대시보드에 등록된 앱이 필요합니다.
앱 등록
- 팀 대시보드에서 Yeap Verify → 앱을 열고 앱 추가를 클릭합니다.
- 이름을 입력합니다. 사용자가 로그인을 승인할 때 Yeap Verify에 이 이름이 표시됩니다.
- 호스팅 페이지를 쓰려면 리디렉션 URI를 한 줄에 하나씩 추가합니다. 결과를 받으려면 필요에 따라 Webhook URL(HTTPS)을 추가합니다.
- 저장을 클릭합니다. Client ID와 Client secret은 한 번만 표시됩니다. 시크릿은 서버에만 저장하세요.


새 시크릿은 시크릿을 교체하며, 이전 시크릿은 즉시 작동을 멈춥니다.
Yeap Verify → 정책에서 앱마다 두 가지 설정이 있습니다.
| 설정 | 의미 |
|---|---|
| Verify가 중단된 경우 | 앱이 Verify에 연결할 수 없을 때 로그인을 차단(기본값)하거나 허용합니다. 이 설정은 앱이 적용하며, 서버 API의 상태 확인이 이 값을 반환합니다 |
| 숫자 자릿수 | 사용자가 입력하는 자릿수로 3~6자리입니다. 민감한 앱에는 더 많은 자릿수를 사용하세요 |
호스팅 로그인 페이지(OpenID Connect)
팀의 로그인 페이지는 https://<team>.verify.yeap.cloud이며, 이것이 issuer이기도 합니다. 구성 정보는 https://<team>.verify.yeap.cloud/.well-known/openid-configuration에 있습니다.
| 흐름 | PKCE(S256)를 사용하는 인가 코드 흐름. scope에 openid가 포함되어야 하고 state는 필수입니다 |
| 클라이언트 인증 | client_secret_basic 또는 client_secret_post |
| ID 토큰 | ES256으로 서명됩니다. 클레임에는 sub(Verify 사용자 ID), preferred_username, amr, tx_id가 포함됩니다 |
| 사용자 지정 | 서버가 서명한 수명이 짧은 JWT인 login_hint_token을 전달합니다(아래 참고). 일반 login_hint는 허용되지 않습니다 |
사용자가 이미 앱에서 비밀번호를 입력했으므로 누구인지 알고 있습니다. 서버는 Client secret으로 서명한 HS256 JWT로 login_hint_token을 만듭니다.
{ "iss": "<client ID>", "aud": "https://acme.verify.yeap.cloud", "sub": "alice", "exp": <now + up to 300 seconds> }그런 다음 response_type=code, client_id, redirect_uri, scope=openid, state, nonce, code_challenge, code_challenge_method=S256, login_hint_token을 붙여 브라우저를 https://acme.verify.yeap.cloud/oauth/v1/authorize로 리디렉션합니다. 페이지에 숫자가 표시되고, 사용자가 휴대폰에서 승인하면 코드와 함께 앱으로 리디렉션됩니다. 이 코드를 구성 정보에 나와 있는 토큰 엔드포인트에서 교환합니다.
서버 API
기본 URL: https://verify.yeap.cloud. 모든 요청은 앱의 Client secret으로 서명합니다.
| 헤더 | 값 |
|---|---|
Yeap-Client-Id | 앱의 Client ID |
Yeap-Timestamp | 현재 Unix 시간(초). 서버 시계와 5분 이내로 차이가 나야 합니다 |
Yeap-Nonce | A–Z a–z 0–9 _ -로 이루어진 16~64자의 임의 문자열로, 요청마다 새로 생성합니다 |
Yeap-Signature | 아래 여섯 줄에 대해 Client secret으로 계산한 HMAC-SHA256의 16진수 값 |
서명 대상 텍스트는 다음 줄을 \n으로 이은 것입니다: yeap-verify-hmac-v1, 메서드, 쿼리 문자열을 포함한 경로, 타임스탬프, nonce, 요청 본문의 SHA-256 16진수 값(GET이면 빈 본문의 값).
엔드포인트
| 요청 | 응답 |
|---|---|
GET /api/v1/health | {"status":"ok","fail_mode":"closed"}. 로그인을 시작하기 전에 호출합니다 |
POST /api/v1/auth | 확인을 시작합니다. 본문: user, factor(push, totp 또는 backup, 기본값 push), 선택 사항인 ip와 app(휴대폰에 표시됨), TOTP와 백업 코드용 passcode |
GET /api/v1/auth/{tx_id} | {"tx_id":…,"status":…} |
status는 처음에 pending이고, 이후 allow, deny, timeout, fraud(사용자가 본인이 아닙니다를 탭함) 중 하나가 됩니다. push의 경우 응답에 사용자에게 보여 줄 number와 expires_at도 포함됩니다. 1~2초마다 폴링하거나 Webhook을 사용하세요. totp와 backup은 응답이 즉시 최종 결과입니다.
예제(Python)
import hashlib, hmac, json, secrets, time
import requests
BASE = "https://verify.yeap.cloud"
CLIENT_ID = "ci_..."
SECRET = "cs_..."
def call(method, path, body=None):
data = json.dumps(body).encode() if body is not None else b""
ts, nonce = str(int(time.time())), secrets.token_urlsafe(24)
text = "\n".join(["yeap-verify-hmac-v1", method, path, ts, nonce, hashlib.sha256(data).hexdigest()])
headers = {
"Yeap-Client-Id": CLIENT_ID, "Yeap-Timestamp": ts, "Yeap-Nonce": nonce,
"Yeap-Signature": hmac.new(SECRET.encode(), text.encode(), hashlib.sha256).hexdigest(),
}
if body is not None:
headers["Content-Type"] = "application/json"
return requests.request(method, BASE + path, data=data, headers=headers, timeout=10).json()
tx = call("POST", "/api/v1/auth", {"user": "alice", "factor": "push", "ip": "203.0.113.7", "app": "Intranet portal"})
print("Enter this number in Yeap Verify:", tx["number"])
while (r := call("GET", "/api/v1/auth/" + tx["tx_id"]))["status"] == "pending":
time.sleep(1.5)
print(r["status"]) # allow, deny, timeout or fraud오류
| HTTP | error | 의미 |
|---|---|---|
| 401 | unauthorized, timestamp_out_of_window, replayed_request | 잘못된 서명 또는 Client ID, 5분 넘게 어긋난 시계, 또는 재사용된 nonce |
| 404 | user_not_found | 해당 이름의 Verify 사용자가 없습니다 |
| 429 | rate_limited | 이 사용자에 대한 요청이 너무 많습니다. 잠시 후 다시 시도하세요 |
| 503 | org_suspended 등("status":"unavailable" 포함) | Verify가 응답할 수 없습니다(예: 요금제 만료). Verify가 중단된 경우 설정을 적용하세요 |
Webhook
앱에 Webhook URL이 있으면 Verify는 각 최종 결과를 JSON 본문 {"event":"auth.result","tx_id":…,"status":…,"reason":…,"at":…}의 POST로 보냅니다. 같은 방식으로 서명되며, 헤더는 X-Yeap-Client-Id, X-Yeap-Timestamp, X-Yeap-Nonce, X-Yeap-Signature이고 Webhook URL의 경로를 대상으로 서명합니다. 신뢰하기 전에 서명을 확인하세요.