黑五年付云服务器 $9.99 起,续费同价。查看特惠

集成你的应用

注册应用,通过托管的 OpenID Connect 页面让用户登录,或调用签名的服务端 API。

5 分钟阅读 更新于 2026年11月8日

你的应用可以通过以下两种方式之一接入 Yeap Verify:

方式适用于
托管登录页(OpenID Connect)已支持 OpenID Connect 的应用。Verify 显示数字并等待批准;你的应用拿到 ID 令牌
服务端 API由你自己添加第二步的应用:推送、TOTP 或备用码

两种方式都需要在团队后台中注册一个应用。

注册应用

  1. 在团队后台中打开 Yeap Verify → 应用,点击 添加应用。
  2. 输入 名称。用户在 Yeap Verify 中批准登录时会看到它。
  3. 如果使用托管登录页,添加你的 回调地址,每行一个。可选添加 Webhook 地址(HTTPS)来接收结果。
  4. 点击 保存。Client ID 和 Client secret 只显示一次。密钥只能保存在你的服务器上。

带 Client ID 的应用列表

新应用及其 Client ID 和密钥

新密钥 会替换密钥;旧密钥立即失效。

在 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
指定用户传入 login_hint_token,即由你的服务器签名的短期 JWT(见下文)。不接受普通的 login_hint

用户已经在你的应用中输入过密码,所以你知道他是谁。你的服务器用 client secret 签名,生成 HS256 JWT 格式的 login_hint_token:

json
{ "iss": "<client ID>", "aud": "https://acme.verify.yeap.cloud", "sub": "alice", "exp": <now + up to 300 seconds> }

然后把浏览器重定向到 https://acme.verify.yeap.cloud/oauth/v1/authorize,并带上 response_type=code、client_id、redirect_uri、scope=openid、state、nonce、code_challenge、code_challenge_method=S256 和 login_hint_token。该页面会显示数字,用户在手机上批准后,会带着授权码重定向回你的应用。在配置中列出的令牌端点用授权码换取令牌。

服务端 API

基础 URL:https://verify.yeap.cloud。每个请求都要用应用的 client secret 签名。

请求头值
Yeap-Client-Id应用的 Client ID
Yeap-Timestamp当前 Unix 时间(秒)。与服务器时钟相差不能超过 5 分钟
Yeap-Nonce16 到 64 个取自 A–Z a–z 0–9 _ - 的随机字符,每个请求都要新生成
Yeap-Signature用 client secret 对下面六行计算的十六进制 HMAC-SHA256

签名文本是以下各行用 \n 连接而成:yeap-verify-hmac-v1、请求方法、带查询字符串的路径、时间戳、nonce,以及请求体的十六进制 SHA-256(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)

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

错误

HTTPerror含义
401unauthorized、timestamp_out_of_window、replayed_request签名或 Client ID 错误、时钟偏差超过 5 分钟,或 nonce 被重复使用
404user_not_found不存在该名称的 Verify 用户
429rate_limited该用户的请求过多。请稍后重试
503org_suspended 等,带 "status":"unavailable"Verify 无法应答,例如套餐已到期。请按你的 Verify 不可用时 设置处理

Webhook

如果应用设置了 Webhook 地址,Verify 会以 POST 请求发送每个最终结果,JSON 请求体为 {"event":"auth.result","tx_id":…,"status":…,"reason":…,"at":…}。它以相同的方式签名,使用请求头 X-Yeap-Client-Id、X-Yeap-Timestamp、X-Yeap-Nonce 和 X-Yeap-Signature,签名路径为你的 webhook URL 的路径。请先校验签名再信任该请求。

本页内容是否有帮助?