管理员登录¶
请求参数¶
仅后台web客户端。必须使用HTTPS和JWE;八项公共元数据必填,clientType=admin、platform=web、channel=admin_web。客户端类型不是管理员认证,App Bearer不能调用后台。
| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
| username | string | 是 | 小写3–32位,首字母a-z,其余a-z0-9_.- |
| password | string | 是 | 非空,最多72个UTF-8字节 |
| rememberMe | boolean | 否 | true保持登录30天;省略、null或false使用原短期会话;不接受字符串、数字或容器 |
请求示例¶
通过管理员统一请求约定加密后发送,下面表示解密后的业务内容。外层使用Accept: application/jose;GET无正文,密文置X-Budyoo-JWE。写请求Origin必须与后台源一致,会话操作另带X-Admin-CSRF;HttpOnly Cookie由浏览器自动携带。
{
"username": "admin",
"password": "使用初始化密码或当前密码",
"rememberMe": true
}
成功响应¶
HTTP200,Cache-Control:no-store。实际外层为JWE,解密后示例:
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"username": "admin",
"role": "OWNER",
"mustChangePassword": false,
"expiresAt": "2026-12-04T12:00:00Z",
"permissions": [
"ADMIN_SESSION",
"ADMIN_USERS_READ",
"ADMIN_USER_PROFILES_READ",
"ADMIN_USER_PROFILES_WRITE",
"ADMIN_CONFIG_READ",
"ADMIN_CONFIG_WRITE",
"ADMIN_AUDIT_READ",
"ADMIN_VERSIONS_READ",
"ADMIN_VERSIONS_WRITE",
"ADMIN_AGREEMENTS_READ",
"ADMIN_AGREEMENTS_WRITE",
"ADMIN_ENFORCEMENT_READ",
"ADMIN_ENFORCEMENT_WRITE"
],
"csrfToken": "64位会话CSRF令牌"
},
"errors": []
}
成功仅在Set-Cookie写入随机会话令牌,JSON不返回令牌。权限和角色由服务器确定;连续5次失败锁定15分钟,来源IP每10分钟最多20次登录,未知账号与错误密码统一401。初始化密码仅创建首个账号时生成,登录后可直接使用;OWNER有配置写权限,VIEWER只读,角色管理页面暂未实现。
rememberMe=true时,Cookie的Max-Age为2592000秒,会话自登录起固定30天有效,不受30分钟空闲限制;读取会话或其他请求不会延长expiresAt。否则Max-Age为28800秒,绝对期限8小时且空闲30分钟失效。Cookie始终Secure、HttpOnly、SameSite=Strict,Path=/api/v1/admin/,绑定本浏览器安装;退出、改密、同安装重新登录和账号停用仍按原规则失效。历史会话不会自动延长,需重新登录并选择保持登录。
网页默认勾选“保持登录30天”,下次在同一浏览器档案中打开会恢复会话。取消勾选可使用短期会话。网页不将密码或会话Token写入localStorage/sessionStorage;用户名与密码输入提供标准autocomplete和name属性,密码是否保存由浏览器密码管理器和用户选择决定。
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | BAD_REQUEST/VALIDATION_FAILED | JSON、查询参数或字段校验失败 |
| 400 | INVALID_CLIENT_HEADERS | 元数据缺失/重复/不合法 |
| 400 | ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST | 缺少真实JWE或认证失败 |
| 401 | UNAUTHORIZED/ADMIN_LOGIN_INVALID | 会话无效、App凭证、登录或旧密码错误 |
| 403 | FORBIDDEN/ADMIN_CSRF_INVALID | 权限不足、来源或CSRF不符 |
| 426 | HTTPS_REQUIRED | 通过HTTP发送后台请求 |
| 429 | TOO_MANY_REQUESTS | 来源IP或网关限流 |
| 503 | SERVICE_UNAVAILABLE | 持久存储或Redis依赖不可用 |
错误按四语公共协议返回,不泄露密码、Cookie或内部异常;无法解密前的错误没有加密响应上下文,不作为已认证业务结果。
接入说明¶
mustChangePassword为兼容保留字段,当前固定false,不再限制权限或页面跳转;有效账号登录后直接按OWNER/VIEWER角色访问后台。保持登录不重置用户当前密码,也不改变OWNER/VIEWER授权。
所有安全和会话约定见后台登录协议,权限由后端每次请求核验。正式凭证不通过未信任TLS链路发送。已通过服务器隔离数据库回归,覆盖独立身份、权限、字段校验和对应失败分支;旧环境曾使用已明确信任的IP证书完成浏览器登录、改密、列表、配置及审计检查。保持登录新增11项隔离回归,覆盖真实JWE、30天固定期限、普通会话默认值、严格布尔值、退出/改密撤销、安装/停用/角色、CSRF/Origin、最多5会话以及V20→V21历史数据兼容。线上通过显式受信TLS和真实JWE验证:勾选保持登录为30天Cookie,取消为8小时Cookie;刷新及关闭整个浏览器后重开可恢复,退出清除Cookie且受保护页面回到登录。候选及线上各16组中英日韩/四种宽度布局通过。当前域名公共CA证书已签发,后台公网入口已发布并完成服务器内TLS校验,管理员创建/角色编辑页面仍待实现。