アプリを連携する
アプリを登録し、ホスト型の OpenID Connect ページでユーザーをサインインさせるか、署名付きサーバー API を呼び出します。
アプリを Yeap Verify に接続する方法は 2 つあります。
| 方法 | 適したケース |
|---|---|
| ホスト型サインインページ(OpenID Connect) | すでに OpenID Connect に対応しているアプリ。Verify が番号を表示して承認を待ち、アプリは ID トークンを受け取ります |
| サーバー API | 2 段階目(プッシュ、TOTP、バックアップコード)を自分で組み込むアプリ |
どちらの場合も、チームダッシュボードにアプリを登録する必要があります。
アプリを登録する
- チームダッシュボードで Yeap Verify → アプリ を開き、アプリを追加 をクリックします。
- 名前 を入力します。ユーザーがサインインを承認するとき、Yeap Verify にこの名前が表示されます。
- ホスト型ページを使う場合は、リダイレクト URI を 1 行に 1 つずつ追加します。結果を受け取るには、必要に応じて Webhook URL(HTTPS)を追加します。
- 保存 をクリックします。Client ID と Client secret は 1 回だけ表示されます。シークレットはサーバー上にのみ保存してください。


新しいシークレット でシークレットを置き換えると、古いシークレットは即座に使えなくなります。
Yeap Verify → ポリシー では、アプリごとに 2 つの設定があります。
| 設定 | 意味 |
|---|---|
| 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 | 以下の 6 行に対する、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 のパスに対して署名されます。信頼する前に署名を確認してください。