# 浏览器登录与回调协议

浏览器完成产品登录时，先访问登录入口，再由UC返回产品回调。两个入口使用导航、Cookie和服务端一次性状态，不按普通PAT JSON请求串接。

## 开始登录

`GET /auth/login`。实际产品前缀由部署配置确定。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

浏览器导航示例，return_to是登录后返回的产品内路径：

```text
GET $PRODUCT_ENDPOINT/auth/login?return_to=%2Fworkspace%2Fexample&lang=zh-CN
```

:::::
:::::{tab-item} 参数说明

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| 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与环境](cookies-environments.md)。

服务端创建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都判为已获得产品会话，应再[读取当前会话](browser-session.md)。

持久化仅对MySQL数字码20702重试，最多三次、间隔100毫秒并使用新事务，取消及时停止；这不是浏览器重放许可。provider、state与持久化错误通常走失败导航，构造失败导航本身失败时可返回500。
