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

OAuth 接口参考

本页内容

在完成 OAuth 接入流程后,用本页核对授权、令牌刷新与撤销的参数和响应。OAuth 端点使用表单和自己的响应格式,与业务 API 分别处理。

调用前准备

先按OAuth 与终端接入登记客户端,并完成所需的用户授权准备。本页的地址使用网站主域名 https://www.onesignios.com,全程 HTTPS。

public 客户端不保管 Client Secret;confidential 客户端在自己的服务端使用 client_secret_post,将 Secret 放在表单字段。令牌和撤销端点不接受 HTTP Basic、Bearer 或 AccessKey 认证头,也不使用业务 API 的幂等键。除 action 外,业务参数放在表单中。

POST 使用 application/x-www-form-urlencoded,正文最多 16 KiB,字段不可重复。OAuth 表单按标准进行 URL 编码;它与 /api/v1/ 的 JSON 请求分别处理。

查询授权服务器信息

发送 GET https://www.onesignios.com/oauth.php?action=metadata。此请求无需 AccessKey 或用户登录。读取以下信息,并将预期 issuer 绑定到自己的接入配置。

字段说明
issuer授权签发方,值为网站 HTTPS 来源。回调中的 iss 必须与预期值相同。
authorization_endpoint在系统浏览器打开的用户授权地址。
token_endpoint交换授权码和刷新令牌的地址。
revocation_endpoint撤销令牌所关联授权的地址。
scopes_supported当前协议支持的动作。实际可授权范围还受账号许可、父 API 应用和用户同意限制。
code_challenge_methods_supported支持 S256。
token_endpoint_auth_methods_supported支持 client_secret_post 和 none,分别用于 confidential 与 public 客户端。

发起用户授权

在系统浏览器打开 GET /oauth.php?action=authorize,将下表字段放在查询串中。用户在平台页面登录、选择自己的应用和权限并确认;第三方程序只接收授权结果,不代替用户填写平台密码。

字段必填说明
client_id是已获准的 OAuth 客户端 ID。它与 API 应用 ID、业务应用 ID 不同。
redirect_uri是客户端已审核的完整 HTTPS 回调地址,须精确一致;使用固定域名和路径,不含查询串、片段或通配符。
response_type是固定为 code。
scope是本次申请的完整动作名称,以单个空格分隔,不重复。最多 20 个,以元数据和实际许可为准。
state是每次授权重新生成的随机值,16–512 个可见 ASCII 字符,并绑定到本次用户会话。
code_challenge是对原 verifier 计算 SHA-256,再做无填充 Base64URL 编码,结果为 43 字符。
code_challenge_method是固定为 S256。

PKCE verifier 为 43–128 位字母、数字或 ._~- 字符,只保存到自己的授权会话,不放在授权 URL。生成和回调校验示例见授权流程。

用户同意后,浏览器以 HTTP 303 跳转到回调地址,查询串包含 code、state 和 iss。用户拒绝时返回 error=access_denied、state 和 iss。先校验 state 与 iss,再处理成功或拒绝;缺少、重复或不匹配的字段应结束本次流程。

授权码只能使用一次,有效期最多 300 秒,且不超过用户授权的剩余时间。收到后及时换取令牌,并使本次本地授权会话失效。

用授权码换取令牌

向 POST /oauth.php?action=token 发送 URL 编码表单。public 与 confidential 客户端都需要 PKCE。

字段必填说明
grant_type是固定为 authorization_code。
client_id是发起授权时使用的客户端 ID。
client_secretconfidential 必填从服务端受保护配置读取;public 客户端不填写。
code是本次回调收到且尚未使用的完整授权码。
redirect_uri是与原授权请求完全相同的回调地址。
code_verifier是本次授权开始前保存的原 verifier。
表单字段示例
grant_type=authorization_code
client_id=<已登记客户端ID>
code=<本次回调的授权码>
redirect_uri=https%3A%2F%2Fclient.example.com%2Foauth%2Fcallback
code_verifier=<原verifier>

上面按行展示字段以方便阅读。实际发送时使用表单编码器将字段连接为 key=value&key=value,不要原样发送多行文本。confidential 客户端另加 client_secret。

成功时 HTTP 200 直接返回下面的对象,不包含业务 API 的 data 包装。响应头提供 X-Request-Id。

令牌响应示例
{
    "access_token": "<接口返回的完整访问令牌>",
    "token_type": "Bearer",
    "expires_in": 300,
    "refresh_token": "<接口返回的完整刷新令牌>",
    "scope": "enterprise:ReadApps"
}

expires_in 为访问令牌的剩余秒数,最多 300 秒。保存整组令牌、取得时间和实际 scope;用户可能只同意了所请求权限的一部分。刷新令牌受原授权和父凭据期限约束,刷新不会延长用户授权期限。

刷新令牌

仍向 POST /oauth.php?action=token 发送表单,字段如下。刷新时不提交 code、redirect_uri 或 code_verifier。

字段必填说明
grant_type是固定为 refresh_token。
client_id是原客户端 ID。
client_secretconfidential 必填仅 confidential 客户端从服务端配置读取。
refresh_token是当前持久保存、尚未使用的完整刷新令牌。
  1. 同一授权使用串行刷新,防止多个线程或服务实例同时消费原令牌。
  2. 成功后原子替换访问令牌与刷新令牌,并让所有调用方使用新值。原访问令牌也会失效。
  3. 刷新令牌或授权码被再次使用时,平台可能撤销这一整组授权。网络超时后不要自动重放旧值;无法可靠取得新令牌时,结束原会话并重新发起用户授权。

调用业务 API 时使用 Authorization: Bearer <access_token>。不发送 AccessKey 签名头;POST 业务请求仍需要 JSON 和原业务幂等键,见认证请求头对照。

撤销授权

向 POST /oauth.php?action=revoke 发送表单。

字段必填说明
client_id是持有此授权的客户端 ID。
client_secretconfidential 必填仅 confidential 客户端使用。
token是本次要结束的授权所关联的完整访问令牌或刷新令牌。
token_type_hint否兼容提示字段,通常可省略;它不改变实际令牌的识别和撤销范围。

撤销成功返回 HTTP 200 和 {}。平台会撤销对应整组用户授权,关联的访问令牌和刷新令牌一并失效。未知、已失效或不属于该客户端的令牌也可以返回相同空对象,因此不能用此响应判断令牌是否曾经存在。

接收成功后清理本地令牌并停止调用。用户也可以在开发者中心撤销自己的第三方授权。更换客户端配置、撤销父凭据或收缩权限后,实际访问范围会相应变化。

处理授权错误

令牌和撤销端点的错误使用 OAuth 格式:error 是字符串,error_description 供人阅读,request_id 用于排查;不要读取 error.code。

OAuth 错误响应示例
{
    "error": "invalid_grant",
    "error_description": "授权码或刷新令牌无效",
    "request_id": "11111111111111111111111111111111"
}
情况处理方式
invalid_request检查方法、表单类型、字段完整性和重复字段;授权请求还需核对精确回调地址与 state。
invalid_client核对客户端 ID、类型与服务端 Client Secret。public 客户端不传 Secret。
invalid_scope从元数据选择支持的动作,核对账号许可、父 API 应用与本次用户同意范围。
invalid_grant核对原授权码、PKCE 和令牌是否过期或已消费;需要重新授权时,让用户重新确认。
unsupported_grant_typegrant_type 使用 authorization_code 或 refresh_token。
access_denied处理用户拒绝,或核对账号、客户端审核状态、Origin 与原授权是否仍有效。结合 HTTP 状态判断。
HTTP 429 或 temporarily_unavailable限制请求频率,保存请求标识;等待服务恢复。已经可能消费的授权码或刷新令牌不做盲目重放。

授权页面返回 HTML 或浏览器重定向,不按 JSON 接口解析。浏览器直连只适用于已批准的 public 客户端来源。日志中保留状态与请求标识,隐藏 code、verifier、Secret 和令牌。