首页 / 开放平台 / 开发帮助 / 开发指南总览

身份授权

开发帮助 更新于 2026-09-21 阅读 11

阅读指引：本篇说明应用获取用户身份的两种方式与开发要点：普通 H5 OAuth2 模式与 JSSDK getAuthCode 模式。接口字段、错误码细节见《用户授权 OAuth2》；JSSDK 引入与 ready/error 生命周期见《JSSDK 快速开始》。

两种授权方式怎么选

方式 适用场景 是否需要 JSSDK
普通 H5 OAuth2 模式 在平台兼容客户端中打开的 H5，直接导航 authorize URL 否
JSSDK getAuthCode 模式 客户端内 H5，已在页面引入 jsapi.js 是（仅用于取 code）

两种方式最终都由应用后端用 code 换用户 Token；普通外部浏览器打开 authorize 地址不能建立平台用户身份，也不能完成授权，不要把它用作独立网页登录入口。

方式一：普通 H5 OAuth2 模式

H5 导航 /oauth2/authorize
  → 平台验证当前登录用户、应用状态、发布范围、回调地址和 Scope
  → 302 跳转到已登记的 redirect_uri，携带 code/state
  → 应用后端校验 state，并用 app_key + app_secret 换用户 Token

授权地址示例：

https://openapi.example.com/openapi/v1/oauth2/authorize
  ?client_id=svc_app_xxx
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=user%3Aprofile%3Aread
  &state=csrf_random_value
query 参数 必填 规则
client_id 是 应用 app_key
redirect_uri 是 与管理员登记的回调 URI 精确一致（协议、主机、端口、路径、query），不支持通配符或 fragment
response_type 是 固定 code
scope 是 一个或多个需要用户授权且已授予应用的 Scope，空格分隔
state 是 应用生成的非空高熵随机值，最多 256 字节；必须校验以防 CSRF

静默授权：从兼容的已登录客户端进入并符合条件时，授权可能直接完成并返回 code，不一定展示确认页。按回调结果处理即可，不要假设每次都弹确认页。

发布范围会在授权链路中重复检查：authorize、换 Token、刷新以及后续用户接口都会复核。用户被移出范围后应结束该用户会话，不要继续刷新旧 Token。

方式二：JSSDK getAuthCode 模式

getAuthCode 在 Bridge ready 后即可调用，不要求先执行 config：

matrix.getAuthCode({
  appKey: 'your_app_key',
  redirectUri: 'https://app.example.com/oauth/callback',
  scopes: ['user:profile:read'],
  state: 'csrf_random_value',
  onSuccess: function(data) {
    // data.authorizationCode / data.state / data.expiresIn
    // 将 code 交给应用后端换用户 Token
  },
  onFail: function(error) {
    console.error(error.code, error.message);
  }
});

authorizationCode 短期有效且只能使用一次；state 原样返回，应用后端必须与发起时保存的值比较。H5 只提交文档化参数，不要附加用户身份、登录凭据或运行环境参数。

用 code 换用户 Token

POST /openapi/v1/oauth2/token，grant_type=authorization_code：

curl -X POST "${OPENAPI_BASE_URL}/openapi/v1/oauth2/token" \
  -u "${APP_KEY}:${APP_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${AUTHORIZATION_CODE}" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback"

响应包含 access_token、refresh_token、expires_in、scope、client_id 与 user_open_id。user_open_id 是当前应用可使用的用户标识，按不透明字符串保存和比较。

刷新与撤销

  • 刷新：仍调用同一 Token endpoint，grant_type=refresh_token。刷新成功后整组 Token 轮换，旧 access token 与旧 refresh token 同时失效，应用必须原子替换本地保存的整组 Token；并发刷新同一旧 refresh token 只允许一次成功。
  • 撤销：POST /openapi/v1/oauth2/user_authorization/revoke，携带用户 Token；scope 传值撤销单个 Scope，省略或空字符串撤销该用户在应用下的全部授权。

获取用户资料与头像

GET /openapi/v1/user/profile 需要用户 Token 与 user:profile:read，只返回 Token 对应的当前用户（不接收用户参数）。响应包含 user_open_id、name 与 avatar（thumbnail_url / original_url / expires_at）。

头像 URL 是短期签名地址（默认 5 分钟，部署上限 15 分钟），直接 GET 下载即可、不需要 Token；篡改、过期或文件不存在统一返回 HTTP 404 空 body。过期后重新请求 profile。

实践建议

  • 应用在获取用户身份后，用 cookie + session 缓存应用内登录状态（建议 3～7 天），避免每次打开都走 OAuth 链路；session 过期后再重新授权。
  • session 建议放 Redis 等共享存储；服务多实例时必须共享，否则会出现登录状态漂移。
  • 权限或应用状态变化导致 Token 失效时按未认证处理并重新走授权，不要循环刷新旧 Token。