如何让FastAPI使用x-gitlab-token请求头完成身份验证

核心原因是你当前使用的默认OAuth2鉴权逻辑只会从Authorization头读取Bearer令牌，而Gitlab Webhook的校验令牌放在自定义的x-gitlab-token头中，调整鉴权依赖的令牌读取逻辑即可解决问题，以下是两种常用方案：

方案1：为Gitlab Webhook接口配置专属鉴权依赖（最推荐） #

该方案不会影响原有接口的鉴权逻辑，权限隔离更安全，适合仅Webhook接口需要支持x-gitlab-token的场景。

1. 先定义Gitlab令牌校验依赖：

from fastapi import Header, HTTPException, status, Depends

# 建议从环境变量读取预设的Gitlab Webhook令牌，不要硬编码
GITLAB_WEBHOOK_TOKEN = "你的预设Gitlab Webhook令牌"

async def verify_gitlab_token(x_gitlab_token: str = Header(None)):
    if x_gitlab_token != GITLAB_WEBHOOK_TOKEN:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="无效或缺失Gitlab Webhook校验令牌"
        )
    return x_gitlab_token

2. 在Gitlab Webhook对应接口上使用该依赖，替换原有全局鉴权依赖即可：

@app.post("/gitlab-webhook-endpoint")
async def handle_gitlab_webhook(
    payload: dict,
    token: str = Depends(verify_gitlab_token)
):
    # 处理Gitlab Webhook逻辑
    return {"status": "success"}

方案2：全局兼容Authorization头与x-gitlab-token #

如果你需要所有接口同时支持两种头传递令牌，可以自定义OAuth2鉴权类，重写令牌读取逻辑：

1. 自定义继承自OAuth2PasswordBearer的鉴权类：

from fastapi.security import OAuth2PasswordBearer
from fastapi import Request, HTTPException, status

class CustomTokenGetter(OAuth2PasswordBearer):
    async def __call__(self, request: Request):
        # 优先读取x-gitlab-token头
        gitlab_token = request.headers.get("x-gitlab-token")
        if gitlab_token:
            return gitlab_token
        # 读取不到则走原有Authorization头逻辑
        auth_header = request.headers.get("Authorization")
        if not auth_header or not auth_header.startswith("Bearer "):
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="未通过鉴权",
                headers={"WWW-Authenticate": "Bearer"},
            )
        return auth_header.split(" ")[1]

2. 替换原有OAuth2PasswordBearer实例即可，原有依赖代码无需修改：

# 替换前
# oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
# 替换后
oauth2_scheme = CustomTokenGetter(tokenUrl="token")

注意事项 #

• 所有鉴权令牌禁止硬编码在业务代码中，建议通过环境变量、配置中心统一管理。
• 若仅Webhook接口需要特殊鉴权，优先选择方案1，避免不必要的权限泄露风险。

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