FastAPI Swagger UI授权按钮无法验证Okta OAuth2令牌

1. 先明确Swagger UI「已认证」的本质 #

Swagger UI的「已认证」状态仅表示它已将你输入的令牌存储在浏览器本地，默认不会主动验证令牌的有效性。只有当你调用需要认证的API接口时，令牌才会被携带到后端，由你的验证逻辑判断是否有效。如果你的API接口已经能正确拦截无效令牌，这其实是Swagger的正常行为——它只是做了令牌存储，而非有效性校验。

2. 若需Swagger授权时即验证令牌，优先切换到授权码模式 #

如果你期望Swagger在点击「Authorize」时就完成有效令牌的获取（而非手动输入），推荐使用Okta的授权码模式，而非密码模式。这种模式下Swagger会自动跳转到Okta的登录页面，只有通过验证的合法令牌会被返回，从根源避免无效令牌输入的问题。

示例配置代码：

from fastapi.security import OAuth2AuthorizationCodeBearer

# 替换为你的Okta域名、客户端ID等信息
oauth2_scheme = OAuth2AuthorizationCodeBearer(
    authorizationUrl="https://your-okta-domain.com/oauth2/default/v1/authorize",
    tokenUrl="https://your-okta-domain.com/oauth2/default/v1/token",
    scopes={"openid": "OpenID Connect", "email": "Access user email"},
    scheme_name="Okta OAuth2"
)

# 后端验证逻辑（API接口调用时触发）
async def verify_token(token: str = Depends(oauth2_scheme)):
    import httpx
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://your-okta-domain.com/oauth2/default/v1/introspect",
            data={
                "token": token,
                "token_type_hint": "access_token",
                "client_id": "your-okta-client-id",
                "client_secret": "your-okta-client-secret"
            }
        )
        resp_data = resp.json()
        if not resp_data.get("active"):
            from fastapi import HTTPException, status
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="Invalid or expired token",
                headers={"WWW-Authenticate": "Bearer"},
            )
    return token

3. 若坚持手动输入令牌，可自定义Swagger验证逻辑（仅测试环境用） #

如果必须保留手动输入令牌的方式，且希望Swagger在授权时就验证令牌有效性，可以通过自定义Swagger UI模板添加前端验证逻辑。注意：这种方式需要暴露Okta客户端密钥在前端，存在安全风险，仅适合测试环境。

步骤如下：

1. 创建自定义Swagger模板文件（如swagger_ui.html），在原有模板基础上添加令牌验证逻辑：

<!-- 保留原Swagger UI模板内容，在SwaggerUIBundle初始化时添加onComplete钩子 -->
<script>
const ui = SwaggerUIBundle({
  url: "{{openapi_url}}",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  layout: "StandaloneLayout",
  onComplete: function() {
    // 重写授权提交逻辑
    const originalAuthorize = ui.authActions.authorizeSubmit;
    ui.authActions.authorizeSubmit = function(payload) {
      fetch('https://your-okta-domain.com/oauth2/default/v1/introspect', {
        method: 'POST',
        headers: {'Content-Type': 'application/x-www-form-urlencoded'},
        body: new URLSearchParams({
          token: payload.value,
          token_type_hint: 'access_token',
          client_id: 'your-okta-client-id',
          client_secret: 'your-okta-client-secret'
        })
      }).then(resp => resp.json())
        .then(data => {
          if (data.active) {
            originalAuthorize(payload);
            alert('令牌验证通过');
          } else {
            alert('无效令牌，请重新输入');
          }
        })
        .catch(err => alert('验证失败：' + err.message));
    };
  }
});
</script>

2. 在FastAPI中指定使用该自定义模板：

from fastapi import FastAPI
from fastapi.openapi.docs import get_swagger_ui_html

app = FastAPI(docs_url=None)

@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        swagger_ui_template="swagger_ui.html",  # 替换为你的模板路径
    )

4. 最后确认后端验证逻辑的完整性 #

虽然你提到API接口认证正常，但仍需确保验证逻辑覆盖所有异常场景：

• 确认正确调用了Okta的introspect端点
• 严格检查返回结果中的active字段是否为True
• 处理令牌过期、签名无效、权限不足等情况

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