Flask RESTX集成Azure AD认证返回401 Unauthorized排查求助

问题背景 #

基于Flask（2.2.3）、Flask-RESTX（1.1.0）搭建的无前端API，使用flask-azure-oauth实现Azure AD用户认证。此前运行正常，近期传入有效令牌时却返回401 Unauthorized（响应体{"message": null}），手动解析令牌无异常，但无法定位拒绝原因。同时，添加的Flask原生错误处理器无法捕获401、404等HTTP异常，仅能捕获非HTTP异常。

认证核心代码 #

from flask import Flask, current_app
from flask_azure_oauth import FlaskAzureOauth
from flask_restx import Api

app = Flask(__name__)
api = Api(app, <...>)
CORS(app)
auth = FlaskAzureOauth()
auth.init_app(app)

# App routes
@api.route("/foo")
class FooCollection(Resource):
    @auth('my_role')
    def get(self):
        return [<...>]

无效的错误处理器代码 #

# Logging request/response
@app.before_request
def log_request_info():
    app.logger.debug(f"{request.method} {request.path} {request.data}")

@app.after_request
def log_response_info(response):
    app.logger.debug(f"{response.status}")
    return response

# Error handling
@app.errorhandler(Unauthorized)
def handle_error(error):
    current_app.logger.debug(f"Oops")
    <...>

@app.errorhandler
def handle_error(error):
    current_app.logger.debug(f"Noooo...!")
    <...>

测试用例代码 #

from werkzeug.exceptions import Unauthorized
from functools import wraps
from flask import jsonify

def unauth():
    def decorator(fn):
        @wraps(fn)
        def wrapper(*args, **kwargs):
            raise Unauthorized("No-no")  # <<<
        return wrapper
    return decorator

@api.route("/dummy")
class Dummy(Resource):
    @unauth()
    def get(self):
        return jsonify(message="Hello there!")

@app.errorhandler(Exception)
def handle_error(error):
    current_app.logger.debug("Intercepted")

解决方案 #

一、修复Flask-RESTX的HTTP错误拦截问题 #

Flask-RESTX的Api实例会接管HTTP异常的处理逻辑，因此原生@app.errorhandler无法捕获这类异常，需通过以下方式处理：

1. 使用Api实例绑定错误处理器
   针对特定HTTP异常（如Unauthorized），直接使用api.errorhandler装饰器：

   from werkzeug.exceptions import Unauthorized
   
   @api.errorhandler(Unauthorized)
   def handle_unauthorized(error):
       current_app.logger.debug(f"Unauthorized details: {error.description}")
       return {"message": error.description or "Authentication failed"}, 401
   

2. 捕获所有HTTP异常
   如需统一处理所有HTTP异常，可注册针对HTTPException的处理器：

   from werkzeug.exceptions import HTTPException
   
   @api.errorhandler(HTTPException)
   def handle_http_errors(error):
       current_app.logger.debug(f"HTTP Error {error.code}: {error.description}")
       return {"message": error.description}, error.code
   

3. 禁用Flask-RESTX默认错误处理（可选）
   若希望完全使用Flask原生错误处理器，初始化Api时设置handle_errors=False：

   api = Api(app, <...>, handle_errors=False)
   

   此方式需自行维护API错误响应格式，但原生@app.errorhandler可正常捕获所有异常。

二、排查Azure AD令牌被拒的具体原因 #

要定位401根源，需从认证流程日志、令牌Claims、配置参数三方面入手：

1. 提升日志级别
   将Flask日志级别设为DEBUG，flask-azure-oauth会输出详细的认证步骤日志，包括令牌签名验证、受众匹配、角色检查等关键信息：

   import logging
   
   app.logger.setLevel(logging.DEBUG)
   

   启动后查看日志中flask_azure_oauth相关输出，可直接定位验证失败的环节。

2. 调试令牌Claims
   包装原认证装饰器，解析令牌Claims用于调试（无需验证签名）：

   from flask import request
   import jwt
   from functools import wraps
   
   def debug_auth(required_role):
       def decorator(fn):
           @wraps(fn)
           def wrapper(*args, **kwargs):
               auth_header = request.headers.get('Authorization')
               if auth_header and auth_header.startswith('Bearer '):
                   token = auth_header.split(' ')[1]
                   try:
                       # 仅解析Claims，跳过签名验证
                       claims = jwt.decode(token, options={"verify_signature": False})
                       current_app.logger.debug(f"Token Claims: {claims}")
                       current_app.logger.debug(f"Expected role: {required_role}, Found roles: {claims.get('roles', [])}")
                   except Exception as e:
                       current_app.logger.debug(f"Token decode failed: {str(e)}")
               # 调用原认证逻辑
               return auth(required_role)(fn)(*args, **kwargs)
           return wrapper
       return decorator
   

   将路由中的@auth('my_role')替换为@debug_auth('my_role')，检查令牌的roles、aud（受众）、iss（签发者）等字段是否与配置匹配。

3. 验证Azure AD配置参数
   确认以下配置是否正确：

   • AZURE_OAUTH_TENANT_ID：Azure AD租户ID是否正确
   • AZURE_OAUTH_CLIENT_ID：是否与令牌的aud字段一致
   • AZURE_OAUTH_SCOPES：是否包含API所需的权限范围
   • AZURE_OAUTH_ROLE_CLAIM：是否与Azure AD中配置的角色Claim名称一致（默认是roles）

内容的提问来源于stack exchange，提问作者Kombajn zbożowy