认证机制

Passport 采用无状态 JWT 作为认证凭据。服务端不保存会话（Session），所有身份信息都封装在 Token 中，由持有公钥的一方在本地完成校验。

早期版本中基于服务端会话（sessionId + passport_session Cookie）的认证方式已在 Go 版本中移除，当前不存在任何 Session 相关接口。

Token 概述

Claims 结构

Token 过期后需重新登录（个人账号）或重新申请（应用账号）。

认证方式一：用户名 / 密码登录

适用于真人用户通过页面或客户端登录的场景。

流程

1. 获取滑块验证码   GET  /api/passport/service/v1/verify/image
2. 校验滑块验证码   POST /api/passport/service/v1/verify/image   →  captchaToken
3. 登录             POST /api/passport/service/v1/login          →  token

第一步：调用「生成滑块验证码」接口，获取底图、拼图块与缺口位置。

第二步：采集用户拖动滑块的落点坐标，以表单格式（point 为 "x,y"）连同 key 提交，换取 captchaToken。校验容差为 4 像素。

第三步：携带 captchaToken、登录名（userId 或 email）与密码调用登录接口。

captchaToken 是登录的必填参数。未携带或校验未通过时，登录接口直接返回 10005 Captcha verification failed，不会校验密码。

登录成功

• 响应体中返回 token 与 username
• 同时下发两个 Cookie：passport_token（Token）与 passport_username（用户名或登录名），有效期由服务端配置决定（默认 86400 秒）

登录失败

登录失败不返回 HTTP 错误码，而是返回 HTTP 200 并在 body 中携带业务错误码，接入方必须解析 code 判断：

连续失败超过服务端配置的阈值（默认 5 次）后账号被锁定；登录成功后失败计数清零。密码以 BCrypt 存储与比对。

登出

调用 DELETE /api/passport/service/v1/login 清除客户端 Cookie。由于服务端无状态，登出不会使 Token 立即失效，已签发的 Token 在过期前仍可通过校验。

认证方式二：AK / SK 换取 Token

适用于服务间调用（应用账号）的场景，无需人工登录。

流程

1. 生成签名   POST /api/passport/service/v1/token/signature  →  signature + timestamp
2. 换取 Token POST /api/passport/service/v1/token            →  token

第一步：提交 accessKeyId 与 secretAccessKey，服务端返回签名与毫秒时间戳。签名算法为：

signature = UPPER(HEX(HMAC-SHA256(secretAccessKey, accessKeyId + timestamp)))

第二步：提交 accessKeyId、timestamp、signature 换取 Token。服务端会重新计算签名比对，并校验应用账号凭证是否存在。

使用 SDK 时，上述两步与 Token 缓存均由 SDK 内部完成，无需手动调用。Go SDK 的 Token 缓存周期为 3600 秒。

服务端如何校验请求

passport-service 按下述顺序处理每一个请求：

1. 请求路径命中配置的鉴权路径模式时进入校验，否则直接放行
2. 注册接口（POST /account）与找回密码接口（/account/forgot-password/*）显式豁免
3. 优先从 Cookie passport_token 读取 Token，为空时读取请求头 passport-token
4. 校验签名与有效期
5. 校验通过则将 acid / uid / tid / pids 写入请求上下文供后续处理使用；校验失败返回 HTTP 401 与 {"code":11002,"message":"Not authorized"}

业务服务接入时无需自行实现上述逻辑，直接使用 SDK 提供的中间件即可，参见「SDK 集成（Java）」与「SDK 集成（Go）」。

修改密码

当前版本不提供已登录状态下的修改密码接口。修改密码请通过「找回密码」流程完成：滑块验证码 → 邮箱验证码 → 重置密码。详见「公开接口」的 Forgot Password 模块。

接入方注意：调用 PUT /api/passport/service/v1/account 更新账号时，请求体中不要携带 password 字段。该接口为全量保存，明文密码会覆盖数据库中的 BCrypt 密文，导致账号永久无法登录。