跳转到主要内容
1签 (OneSign)

OAuth 与终端接入

本页内容

网页、Vue 和移动端可以在用户同意后访问其选定应用,也可以通过自己的服务端调用 API。使用 OAuth 时,需要完成客户端登记、PKCE 授权和令牌管理。

选择终端接入方式

方案适用情况凭据放在哪里
通过自己的服务端调用已有后端,由后端完成认证与业务处理长期 Secret 保存在后端
OAuth 用户授权需要用户明确选择应用并同意第三方访问终端只持有授权令牌,不内置长期 Secret

下面说明 OAuth 流程。浏览器、Vue 和移动端使用 public 客户端;能保管 Client Secret 的服务端可使用 confidential 客户端。

登记 OAuth 客户端

  1. 在开发者中心登记用途、客户端类型和精确 HTTPS 回调地址,完成接入申请。
  2. 从授权服务器元数据读取 issuer、端点、支持的 scope 和认证方法。
  3. 确定最少需要的动作。终端上传或签名还需对应独立许可,并仅操作用户选定的已有应用。

客户端登记不等于获得用户授权。实际可访问范围以本次用户同意及当前平台授权为准。各端点的完整字段、响应和错误说明见OAuth 接口参考。

取得授权码并换取令牌

  1. 为每次授权生成随机 state 和 PKCE verifier,并与这次用户会话一起保存。
  2. 用 verifier 的 SHA-256 原始摘要计算无填充 Base64URL challenge。
  3. 在系统浏览器打开授权端点,填写 client_id、精确 redirect_uri、response_type=code、scope、state、code_challenge 和 code_challenge_method=S256。
  4. 回到登记地址后,先核对 state 与 iss,再使用原 verifier 将一次性 code 换为令牌。
Python SDK
import base64
import hashlib
import hmac
import secrets

def new_oauth_attempt():
    verifier = secrets.token_urlsafe(32)
    challenge = base64.urlsafe_b64encode(
        hashlib.sha256(verifier.encode("ascii")).digest()
    ).rstrip(b"=").decode("ascii")
    return {"state": secrets.token_urlsafe(32),
            "verifier": verifier, "challenge": challenge}

def validate_oauth_callback(expected_state, state, expected_issuer, issuer):
    if not all(isinstance(value, str) and value for value in
               (expected_state, state, expected_issuer, issuer)):
        raise ValueError("授权响应缺少 state 或 iss")
    if not hmac.compare_digest(expected_state.encode(), state.encode()):
        raise ValueError("授权 state 不匹配")
    if not hmac.compare_digest(expected_issuer.encode(), issuer.encode()):
        raise ValueError("授权签发方不匹配")
换取令牌的表单字段
POST /oauth.php?action=token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<客户端ID>&redirect_uri=<编码后的原回调地址>&code=<授权码>&code_verifier=<原verifier>

scope 中多个动作以空格分隔,作为查询参数时进行 URL 编码。confidential 客户端在受信服务端另传 client_secret;public 客户端不内置此 Secret。用户拒绝授权或回调校验失败时结束本次流程。

使用、刷新与撤销

使用 Authorization: Bearer <access_token> 请求已授权的 API。写入仍需 JSON 和幂等键;浏览器直连还需批准精确 Origin。

根据响应中的 expires_in 管理有效期。刷新时向 Token 端点提交 grant_type=refresh_token、当前 refresh_token 和 client_id,并按客户端类型完成认证。成功后原子替换整组令牌,同一会话不要并发刷新。访问令牌也会随刷新替换;旧刷新令牌再次出现可能使整组授权撤销。

退出或撤权时使用 /oauth.php?action=revoke,它会撤销对应整组授权。令牌和 Secret 不写入 URL、公开日志或跨站共享存储。响应丢失等情况按刷新与恢复说明处理。

确认授权与异常处理

先执行当前身份或一个已选应用的只读查询。401 时核对令牌是否过期、刷新是否已替换旧值;403 或 404 时核对用户同意的动作、应用范围和功能许可。不要通过重新登录跳过用户同意,也不要将 Bearer 与 CS1 请求头一起发送。