浏览器登录与回调协议¶
浏览器完成产品登录时,先访问登录入口,再由UC返回产品回调。两个入口使用导航、Cookie和服务端一次性状态,不按普通PAT JSON请求串接。
开始登录¶
GET /auth/login。实际产品前缀由部署配置确定。
浏览器导航示例,return_to是登录后返回的产品内路径:
GET $PRODUCT_ENDPOINT/auth/login?return_to=%2Fworkspace%2Fexample&lang=zh-CN
参数 |
位置 |
说明 |
|---|---|---|
return_to |
query |
可选产品内相对路径;与product_continuation互斥;两者均省略时service采用/ |
product_continuation |
query |
可选、服务端签发的一次性交接值;与return_to互斥,不由调用者伪造 |
lang |
query |
可选账号登录UI语言:zh-CN、en-US、fr-FR、es-ES、ar、id-ID;区分大小写 |
显式空return_to或product_continuation、重复目标参数和同时提供两个目标进入失败导航。重复lang或不支持的lang直接400/ErrParamInvalid。相对目标最大2048字节,以单/开头,不以//开头,不含反斜线,URL解析后没有Host/User/绝对URI/opaque部分。不要以此规则替代完整生产域名与回调配置验证。
成功返回302、Location和该次登录绑定Cookie。跳转到UC授权页后继续完整流程;302不表示登录已完成。浏览器/调用方需要保留正确origin和路径下的Cookie,具体规则见Cookie与环境。
服务端创建state、nonce、PKCE verifier和绑定值;UC授权URL采用S256挑战并带产品continuation。已有continuation的消费与后继登录状态创建在同一系统事务,失败不能让调用者自行重复使用旧交接值。使用continuation时,UI语言沿用其签发状态携带的语言,lang不覆盖该状态。TTL来自部署配置,不从测试值推为默认值。
完成登录回调¶
GET /auth/callback。该地址由UC导航返回,业务调用者不自行拼接令牌兑换请求。
参数 |
位置 |
当前消费 |
|---|---|---|
state |
query |
服务端签发的状态值;handler取第一个值,必须与绑定Cookie及尚未消费记录匹配 |
code |
query |
授权码;与非空error恰有一个非空 |
error |
query |
上游失败标识;与非空code互斥 |
逐state的绑定Cookie优先;只有该Cookie不存在时才读取旧固定绑定Cookie。重复Cookie、缺少绑定或非法状态导致失败导航。state包含界面语言后缀时,完整值参与存储hash;Cookie名称的token部分不含该后缀。
回调依次消费state及关联continuation、兑换并验证令牌、核对nonce和UC活跃会话/subject,再持久化产品身份与会话。一次性状态消费事务在UC兑换之前已提交;整个回调不是跨UC和本地存储的单一原子事务。下游失败后不要自动重放原回调。
成功时设置产品会话和CSRF Cookie,清除本次登录绑定Cookie,302回原安全目标。UC会话inactive或缺handle时可重新发起一次登录并清旧会话Cookie;再次失败进入失败页。不能把任意302都判为已获得产品会话,应再读取当前会话。
持久化仅对MySQL数字码20702重试,最多三次、间隔100毫秒并使用新事务,取消及时停止;这不是浏览器重放许可。provider、state与持久化错误通常走失败导航,构造失败导航本身失败时可返回500。