litestar-authentication

身份验证

执行工作流

1. 先根据客户端和信任边界选择身份验证机制：会话、JWT 请求头、JWT Cookie、OAuth2 密码持有者或自定义中间件。
2. 使用 on_app_init 或中间件，在应用级别附加一次身份验证。
3. 明确配置登录、架构、健康检查和其他公开路由的排除规则。
4. 只有在身份验证已完成后，才能使用 request.user 和 request.auth。
5. 单独应用守卫进行授权检查。
6. 保持缺少凭据或凭据无效时的行为与异常处理策略一致。

核心规则

• 将身份验证与请求解析和授权分开。
• 尽可能先通过请求解析验证输入字段，再处理身份验证相关的业务逻辑。
• 优先使用内置安全后端，而非自定义中间件。
• 只有当身份来源不适用于内置后端时，才使用自定义中间件。
• 将 request.user 和 request.auth 视为经过身份验证的上下文，而非解析捷径。
• 保持排除规则精简且便于审核。
• 除非项目有明确记录的替代方案，否则将身份验证失败统一处理为 401。

选择指南

• 对于以浏览器为主且使用服务端管理会话的应用，使用 SessionAuth。
• 对于在请求头中携带令牌的 API 客户端，使用 JWTAuth。
• 对于有意使用令牌 Cookie 的浏览器流程，使用 JWTCookieAuth。
• 当需要密码流程的令牌签发语义时，使用 OAuth2PasswordBearerAuth。
• 当凭据来源或验证逻辑为自定义时，使用 AbstractAuthenticationMiddleware。
• 当任务涉及超出身份接入范畴的授权策略、机密信息和纵深防御问题时，使用 litestar-security。

参考文件

只阅读所需章节：

• 有关自定义中间件、内置后端、请求身份验证上下文、排除规则和登录模式，请阅读 references/auth-patterns.md。

建议默认设置

• 在应用级别注册身份验证中间件或后端。
• 只排除明确公开的路由。
• 身份验证运行后，通过带类型的 Request 或 ASGIConnection 访问经过身份验证的上下文。
• 明确令牌签发和注销流程，并确保它们可测试。
• 将 401 / 403 响应格式交由 litestar-exception-handling 处理。

反模式

• 在每个路由处理程序中手动解析身份验证请求头。
• 将授权策略混入身份验证中间件。
• 将 request.user 视为在被排除于身份验证之外的路由上也可用。
• 使用范围过大的路径排除规则，意外扩大公开面。
• 在本地示例之外硬编码机密信息或示例令牌。

验证清单

• 确认受保护的端点会拒绝缺少凭据或凭据无效的请求。
• 确认只有明确排除的公开路由才是公开的。
• 确认经过身份验证的路由上的 request.user 和 request.auth 类型符合预期。
• 确认登录和注销流程会产生预期的令牌或会话行为。
• 确认身份验证失败符合异常处理约定。
• 确认测试覆盖已通过和未通过身份验证的路径。

跨技能交接

• 对于与身份验证无关的请求头、Cookie 和请求体解析问题，使用 litestar-requests。
• 对于授权、机密信息卫生和更广泛的安全态势问题，使用 litestar-security。
• 使用 litestar-exception-handling 统一 401 和 403 约定。
• 使用 litestar-testing 编写身份验证边界、排除规则和令牌流程测试。

Litestar 参考资料

• https://docs.litestar.dev/latest/usage/security/abstract-authentication-middleware.html
• https://docs.litestar.dev/latest/usage/security/security-backends.html
• https://docs.litestar.dev/latest/usage/security/jwt.html
• https://docs.litestar.dev/latest/usage/security/excluding-and-including-endpoints.html