starlette 集成 oauth2 认证的核心做法是结合 starlette.authentication 模块与第三方库(如 authlib)来处理授权流程。具体而言,你需要定义一个自定义的 authenticationbackend 来解析请求头中的 bearer token,并通过 @authenticate() 装饰器保护路由。这样做能确保只有携带有效凭证的请求才能访问受保护的资源,未认证的请求会被自动拦截并返回 401 状态码。

如何配置自定义认证后端以验证 JWT Token
通过继承 BaseBackend 并重写 authenticate 方法,可以实现基于 JWT 的 Token 验证逻辑。在 authenticate 方法中,从请求头提取 Token 并使用 PyJWT 库进行解码和校验,若成功则返回包含用户信息的 SimpleUser 对象,否则返回 None。这一步骤是将标准 HTTP 请求转换为 Starlette 内部认证上下文的关键。

from starlette.authentication import AuthenticationBackend, SimpleUser
from starlette.requests import Request
import jwt
class JWTAuthBackend(AuthenticationBackend):
def __init__(self, secret_key: str):
self.secret_key = secret_key
async def authenticate(self, request: Request):
auth_header = request.headers.get("Authorization")
if not auth_header or not auth_header.startswith("Bearer "):
return None
token = auth_header.split(" ")[1]
try:
payload = jwt.decode(token, self.secret_key, algorithms=["HS256"])
user = SimpleUser(payload["sub"], is_authenticated=True)
return user
except jwt.InvalidTokenError:
return None
如何在路由中使用装饰器保护端点
使用 @authenticate(JWTAuthBackend) 装饰器可以直接应用于 Starlette 的路由函数,从而自动执行认证检查。当请求到达时,装饰器会调用后端逻辑,若认证成功,用户信息将注入到 request.user 中供业务逻辑使用;若失败,框架会自动终止请求并返回错误响应。这种机制避免了在每个路由中手动编写重复的鉴权代码。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import JSONResponse
from starlette.authentication import requires
# 假设 backend 已实例化
backend = JWTAuthBackend(secret_key="my-secret")
@requires("is_authenticated", redirect="/login")
async def protected_view(request):
# request.user 在此处已确认为已认证用户
return JSONResponse({"user": request.user.display_name})
app = Starlette(routes=[Route("/protected", protected_view)])
当 Token 过期或无效时系统返回什么结果
当 Token 过期或签名无效时,authenticate 方法会捕获异常并返回 None,导致 @requires 装饰器触发默认的重定向行为或返回 401 错误。具体表现取决于装饰器的配置:若指定了 redirect 参数,用户将被重定向至登录页;若未指定,客户端将收到一个标准的 401 Unauthorized 响应,表明当前凭据无法通过验证。










