FastAPI异常处理器重定向至外部页面时遇IDP 404问题求解

问题核心原因 #

通过异常处理器间接重定向到SAML登录端点时，IDP返回404的常见原因包括：

• 重定向路径与后端登录端点不匹配
• SAML请求生成时丢失原始请求上下文，导致回调URL或请求参数不符合IDP要求
• Nginx反向代理未正确传递必要请求头，FastAPI无法生成正确的外部请求信息

修复步骤 #

1. 修正重定向路径并传递原始请求URL #

修改异常处理器，将用户原本访问的URL编码后作为参数传递，同时确保重定向路径与后端登录端点一致：

from urllib.parse import quote
from starlette.exceptions import StarletteHTTPException

@app.exception_handler(StarletteHTTPException)
async def unauthorized_handler(request: Request, exc):
    # 编码原始请求URL，作为登录成功后的跳转目标
    next_url = quote(str(request.url))
    # 若Nginx配置了/api前缀转发，路径改为/api/saml/login
    redirect_url = f"/saml/login?next={next_url}"
    return RedirectResponse(url=redirect_url)

2. 调整登录端点使用动态return_to #

修改登录端点，用传递的next参数替代硬编码的跳转地址，保证登录后回到用户原本访问的页面：

@app.get("/saml/login")
async def sso(request: Request):
    req = await prepare_from_fastapi_request(request)
    # 获取用户原本要访问的URL，默认回主页
    return_to_url = request.query_params.get("next", "https://website.com/")
    auth = Saml2_Auth_patched(req, saml_settings)
    callback_url = auth.login(return_to=return_to_url)
    return RedirectResponse(url=callback_url)

3. 确保Nginx反向代理传递必要头信息 #

在Nginx配置中添加以下内容，保证FastAPI能获取到正确的外部请求上下文：

location /api {
    proxy_pass http://your-fastapi-backend:port;
    # 传递关键请求头，用于生成正确的SAML请求URL
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

4. 验证SAML配置正确性 #

检查saml_settings中的核心配置是否与IDP侧完全一致：

• entity_id: 你的应用实体ID
• acs_url: IDP回调到你的应用的断言消费服务地址
• idp_metadata_url/idp_entity_id: IDP的元数据地址或实体ID

额外排查点 #

• 查看IDP侧日志，确认404是因回调端点不存在还是请求参数错误
• 检查浏览器网络请求，确认重定向过程中请求头是否完整
• 直接访问带next参数的登录端点，验证是否能正常跳转至IDP并回调

内容的提问来源于stack exchange，提问作者fredd5229