3. 鉴权失败类型分析

在 OpenAPI 鉴权流程中，失败并非单一原因。不同的失败类型对应不同的错误码、不同的安全风险等级，以及不同的模板引擎降级策略。只有精确区分失败类型，才能设计出既安全又用户友好的降级渲染方案。

设计原则：鉴权失败后的渲染降级不是简单的“全部显示错误页”，而是根据失败类型决定是否重试、是否展示缓存、是否提示用户重新登录、是否记录安全告警。

3.1 五种鉴权失败类型总览

根据 RFC 6750（Bearer Token Usage）及主流 API 网关实践，鉴权失败可归纳为以下五种核心类型：

失败类型 HTTP 状态码 典型错误码 安全等级 是否可自动重试
令牌过期 401 TOKEN_EXPIRED 低 是（刷新令牌）
令牌无效 401 INVALID_TOKEN 中 否
权限不足 403 INSUFFICIENT_PERMISSIONS 中 否
签名错误 401 SIGNATURE_MISMATCH 高 否
黑名单拒绝 403 TOKEN_REVOKED 高 否
关键区分：401 与 403 的区别在于——401 表示“你是谁？请证明身份”；403 表示“我知道你是谁，但你不被允许做这件事”。两种状态在降级渲染时展示的信息完全不同。

3.2 令牌过期（Token Expired）

令牌过期是最常见的鉴权失败类型。JWT（JSON Web Token）通常包含 exp（过期时间）声明，服务端在验证时会检查当前时间是否已超过 exp 值。

// JWT 令牌过期验证伪代码
function verifyToken(token) {
    const payload = decodeJWT(token);
    if (payload.exp < Date.now() / 1000) {
        return { valid: false, reason: 'TOKEN_EXPIRED', exp: payload.exp };
    }
    // 继续其他验证...
}

降级策略：

  • 客户端应尝试使用 Refresh Token 自动获取新 Access Token。
  • 若刷新成功，模板引擎使用新令牌重新发起请求，用户无感知。
  • 若刷新失败（如 Refresh Token 也过期），则降级为登录引导页。
  • 模板渲染时，可保留用户当前页面状态（如表单填写内容），避免数据丢失。

3.3 令牌无效（Invalid Token）

令牌无效指令牌格式错误、被篡改、签名不匹配（但非主动伪造）、或使用了错误的令牌类型。常见原因包括：

  • 令牌字符串被截断或包含非法字符。
  • 令牌使用了错误的密钥或算法进行解码。
  • 令牌来自不同的颁发机构（Issuer）。

降级策略：

  • 不允许自动重试，因为重试同样会失败。
  • 清除本地存储的无效令牌。
  • 模板引擎渲染“会话异常”页面，提示用户重新登录。
  • 记录安全日志，标记为“令牌格式异常”。

3.4 权限不足（Insufficient Permissions）

令牌有效且未过期，但当前用户角色或权限不满足 API 的资源访问要求。例如普通用户尝试访问管理员接口。

// 权限检查示例
function checkPermission(user, requiredRole) {
    if (user.role !== requiredRole && !user.roles.includes(requiredRole)) {
        return { allowed: false, reason: 'INSUFFICIENT_PERMISSIONS' };
    }
    return { allowed: true };
}

降级策略：

  • 模板引擎渲染“无权限访问”页面，而非直接显示空白或错误堆栈。
  • 可展示用户当前角色与所需角色的对比信息（注意不要泄露敏感权限结构）。
  • 提供“联系管理员”或“申请权限”的入口链接。
  • 不自动重试，避免造成服务端无意义的权限校验开销。

3.5 签名错误（Signature Mismatch）

签名错误通常意味着令牌在传输过程中被篡改，或使用了错误的签名密钥。这是安全等级最高的鉴权失败类型之一，可能表明存在中间人攻击或令牌伪造尝试。

降级策略：

  • 立即拒绝，不返回任何业务数据。
  • 模板引擎渲染通用“服务不可用”或“请求异常”页面，不透露具体原因。
  • 触发安全告警，记录请求来源 IP、User-Agent、令牌前几位哈希。
  • 客户端清除所有本地令牌，强制重新登录。
安全提示：签名错误的错误信息不应直接暴露给前端。服务端应返回统一的 401 错误码，错误描述使用“Authentication failed”等模糊文案，防止攻击者获取签名验证细节。

3.6 黑名单拒绝（Token Revoked / Blacklisted）

令牌已被服务端主动撤销，常见场景包括：用户主动登出、管理员强制下线、检测到异常登录行为、令牌在其它设备被刷新等。

// 黑名单检查示例（Redis 实现）
async function isTokenBlacklisted(jti) {
    const exists = await redis.exists(`blacklist:${jti}`);
    return exists === 1;
}

降级策略：

  • 模板引擎渲染“会话已失效”页面，提示用户可能已在其他设备登录。
  • 清除本地令牌和缓存数据。
  • 若为主动登出场景，可展示“您已成功登出”的友好提示。
  • 若为强制下线场景，可展示“您的账号在其他设备登录”的安全提示。

3.7 鉴权失败类型决策流程

以下 SVG 流程图展示了服务端收到鉴权失败响应后，根据失败类型选择不同降级路径的决策逻辑：

鉴权失败类型决策流程图 收到鉴权失败响应 失败类型？ 令牌过期 令牌无效 权限不足 签名错误 黑名单拒绝 根据类型选择降级渲染策略 重试 / 刷新令牌 / 引导登录 / 展示无权限页 / 安全告警

3.8 降级渲染策略对照表

根据上述五种失败类型，模板引擎应采用不同的渲染策略。以下对照表总结了各类型的推荐行为：

失败类型 渲染模板 是否保留页面状态 是否触发安全告警 用户提示文案示例
令牌过期 静默刷新 → 登录引导页 是 否 “登录已过期，请重新登录”
令牌无效 会话异常页 否 是（低优先级） “会话异常，请重新登录”
权限不足 无权限提示页 是 否 “您没有权限执行此操作”
签名错误 通用错误页（模糊文案） 否 是（高优先级） “请求异常，请稍后重试”
黑名单拒绝 会话已失效页 否 是（中优先级） “会话已失效，请重新登录”
最佳实践：在模板引擎中为每种失败类型预定义独立的渲染模板文件（如 token_expired.html、permission_denied.html），并在鉴权中间件中根据错误码动态选择模板。避免在业务代码中硬编码 HTML 片段。

3.9 失败类型与降级路径映射

以下 SVG 图展示了从鉴权失败类型到具体降级渲染路径的完整映射关系：

鉴权失败类型 → 降级渲染路径映射 令牌过期 令牌无效 权限不足 签名错误 黑名单拒绝 尝试刷新令牌 成功→继续；失败→降级 清除令牌 不重试，直接降级 保留令牌 展示无权限页 安全告警 模糊错误文案 清除令牌 展示会话失效页 渲染：登录引导页 保留页面状态 渲染：会话异常页 不保留状态 渲染：无权限页 保留页面状态 渲染：通用错误页 模糊文案，不保留状态 渲染：会话失效页 不保留状态 核心原则：安全敏感型失败（签名错误、黑名单）→ 模糊文案 + 安全告警 业务敏感型失败（令牌过期、权限不足）→ 友好提示 + 保留用户操作上下文

3.10 实践建议

  • 统一错误码规范：在团队内部定义统一的鉴权错误码枚举，确保前端、后端、模板引擎三方使用同一套错误码体系。
  • 区分客户端与服务器端渲染：若使用 SSR（服务器端渲染），鉴权失败应在服务器端直接选择降级模板；若使用 CSR（客户端渲染），应通过 API 响应中的错误码驱动前端路由切换。
  • 避免信息泄露：签名错误、黑名单拒绝等安全敏感类型，不要在前端展示具体原因，防止攻击者利用错误信息进行进一步攻击。
  • 监控与告警：对签名错误和黑名单拒绝设置实时告警，监控异常频率，及时发现潜在的安全攻击。
← 上一章 📖 返回目录 下一章 →