Auth0 Flask Web App 集成

使用 auth0-server-python 为 Flask Web 应用添加登录、登出和用户资料功能。

前提条件

• Flask 应用
• 已配置的 Auth0 常规 Web 应用（非 API — 必须是 Application 类型）
• 若尚未配置 Auth0，请先使用 auth0-quickstart 技能

不适用场景

• 使用 JWT Bearer 验证的 Python API — 对 FastAPI 使用 auth0-fastapi-api，或参考 Django REST Framework 快速入门指南
• 带登录/登出 UI 的 FastAPI Web 应用 — 当前尚无专用技能；请参阅 FastAPI 快速入门指南
• 单页应用（SPA） — 客户端鉴权请使用 auth0-react、auth0-vue 或 auth0-angular
• Next.js 应用 — 使用 auth0-nextjs，它同时支持客户端与服务端逻辑
• Node.js Web 应用 — 使用 auth0-express 或 auth0-fastify 实现基于会话的身份验证

快速开始工作流

1. 安装 SDK

pip install auth0-server-python "flask[async]" python-dotenv

关键注意：必须安装 flask[async]（而非仅 flask）。[async] 扩展将安装 asgiref，这是 Flask 2.0+ 支持 async def 路由处理器所必需的。缺少该依赖会导致异步路由无法正常工作。在 requirements.txt 中应使用 flask[async]>=2.0.0。

2. 配置环境变量

创建 .env 文件：

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_SECRET=your_generated_app_secret
AUTH0_REDIRECT_URI=http://localhost:5000/callback

AUTH0_DOMAIN 是你的 Auth0 租户域名（不含 https://）。AUTH0_CLIENT_ID 和 AUTH0_CLIENT_SECRET 来自 Auth0 应用设置页面。AUTH0_SECRET 用于加密会话数据，可通过 openssl rand -hex 64 生成。

3. 配置 Auth0 控制台

在 Auth0 应用设置中：

• 允许的回调 URL（Allowed Callback URLs）：http://localhost:5000/callback
• 允许的登出 URL（Allowed Logout URLs）：http://localhost:5000

4. 创建鉴权模块

创建 auth.py，使用 Flask 的会话机制初始化 ServerClient。这些存储器默认使用 Flask 内置的 session（基于 Cookie）实现无状态（stateless）部署，无需外部数据库：

import os
from flask import session as flask_session
from auth0_server_python.auth_server.server_client import ServerClient
from auth0_server_python.auth_types import StateData, TransactionData
from auth0_server_python.store import StateStore, TransactionStore
from dotenv import load_dotenv

load_dotenv()  # 默认读取 .env；如凭据存于 .env.local，请传入 load_dotenv(".env.local")


class FlaskSessionStateStore(StateStore):
    """使用 Flask session 持久化状态的存储器。"""

    def __init__(self, secret: str):
        super().__init__({"secret": secret})

    async def set(self, identifier, state, remove_if_expires=False, options=None):
        data = state.dict() if hasattr(state, "dict") else state
        flask_session[identifier] = self.encrypt(identifier, data)

    async def get(self, identifier, options=None):
        data = flask_session.get(identifier)
        if data is None:
            return None
        decrypted = self.decrypt(identifier, data)
        # 确保不返回 dict 类型，底层 SDK 期望的是 StateData 实例而非字典
        return StateData(**decrypted) if isinstance(decrypted, dict) else decrypted

    async def delete(self, identifier, options=None):
        flask_session.pop(identifier, None)

    async def delete_by_logout_token(self, claims, options=None):
        pass


class FlaskSessionTransactionStore(TransactionStore):
    """使用 Flask session 持久化事务的存储器。"""

    def __init__(self, secret: str):
        super().__init__({"secret": secret})

    async def set(self, identifier, state, remove_if_expires=False, options=None):
        data = state.dict() if hasattr(state, "dict") else state
        flask_session[identifier] = self.encrypt(identifier, data)

    async def get(self, identifier, options=None):
        data = flask_session.get(identifier)
        if data is None:
            return None
        decrypted = self.decrypt(identifier, data)
        # 确保不返回 dict 类型，底层 SDK 期望的是 TransactionData 实例而非字典
        return TransactionData(**decrypted) if isinstance(decrypted, dict) else decrypted

    async def delete(self, identifier, options=None):
        flask_session.pop(identifier, None)


secret = os.getenv("AUTH0_SECRET")

auth0 = ServerClient(
    domain=os.getenv("AUTH0_DOMAIN"),
    client_id=os.getenv("AUTH0_CLIENT_ID"),
    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
    secret=secret,
    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),
    state_store=FlaskSessionStateStore(secret=secret),
    transaction_store=FlaskSessionTransactionStore(secret=secret),
    authorization_params={"scope": "openid profile email"},
)

创建一个 ServerClient 实例并复用它。切勿硬编码凭证 —— 务必始终通过环境变量加载。

原理说明： Flask 默认会话基于 Cookie（无状态）。SDK 在将令牌、用户资料等数据写入会话前，使用 JWE 进行加密，确保 Cookie 中的数据既被签名又加密。无需服务端数据库。

无需 store_options 或 before_request： SDK 支持向存储方法传递 store_options（例如 request/response 对象）。由于本示例中的存储器使用 flask.session（在请求生命周期内全局可用），因此不需要从 store_options 获取任何参数，可直接调用 SDK 方法而无需传入该参数。若你实现了一个直接管理 Cookie 的自定义存储器（而非使用 flask.session），则需重新引入 store_options 并传入 {"request": request, "response": response}。

关于 Cookie 大小： 无状态会话将全部数据存于 Cookie（约 4KB 上限），对大多数应用已足够。若存储大量会话数据或接近 Cookie 大小限制，请切换至有状态（stateful）部署方案。

5. 配置 Flask 应用

在 app.py 中，配置 Flask 的密钥及会话选项：

import os
from flask import Flask, redirect, request
from auth import auth0
from dotenv import load_dotenv

load_dotenv()

app = Flask(__name__)
app.secret_key = os.getenv("AUTH0_SECRET")
app.config.update(
    SESSION_COOKIE_SECURE=False,  # 生产环境需设为 True（要求 HTTPS）
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SAMESITE="Lax",
)

关键注意： 必须设置 app.secret_key，否则 Flask 会话机制无法工作。

生产环境注意事项： 部署于 HTTPS 环境时，必须将 SESSION_COOKIE_SECURE 设为 True。若在生产环境中保持 False，会话 Cookie 将通过未加密连接传输。

6. 添加首页路由

@app.route("/")
async def home():
    user = await auth0.get_user()
    if user:
        return f"Hello, {user['name']}! Profile | Logout"
    return "Welcome! Login"

7. 添加登录路由

@app.route("/login")
async def login():
    authorization_url = await auth0.start_interactive_login()
    return redirect(authorization_url)

start_interactive_login() 返回指向 Auth0 通用登录页（Universal Login Page）的 URL 字符串，你必须将其包裹在 redirect() 中。授权参数（如 scope、redirect_uri）已在 ServerClient 初始化时配置完成。

8. 添加回调路由

@app.route("/callback")
async def callback():
    try:
        await auth0.complete_interactive_login(str(request.url))
        return redirect("/")
    except Exception as e:
        return f"Authentication error: {str(e)}", 400

第一个参数必须传入 str(request.url) —— 即包含授权码查询参数的完整回调 URL。务必用 try/except 包裹，因为令牌交换可能失败（例如授权码过期、CSRF 校验失败）。

9. 添加受保护的资料页路由

@app.route("/profile")
async def profile():
    user = await auth0.get_user()
    if user is None:
        return redirect("/login")
    return (
        f"
{user['name']}
"
        f"
Email: {user['email']}
"
        f""
        f"
Logout
"
    )

get_user() 从会话中返回当前用户资料，若未登录则返回 None。

10. 添加登出路由

@app.route("/logout")
async def logout():
    url = await auth0.logout()
    return redirect(url)

logout() 返回 Auth0 的登出 URL，需重定向用户至此地址。

11. 测试应用

flask run

访问 http://localhost:5000/login 启动登录流程。

基于 Redis 的有状态（Stateful）部署

对于生产环境应用，或当会话数据超出 Cookie 大小限制时，可使用 Flask-Session 配合 Redis 将会话数据存储在服务端。此时 Cookie 中仅保存会话 ID。

1. 安装依赖

pip install flask-session redis

2. 配置 Flask-Session

更新 app.py 以启用 Redis 后端会话：

import os
from flask import Flask, redirect, request
from flask_session import Session
from auth import auth0
from dotenv import load_dotenv

load_dotenv()

app = Flask(__name__)
app.secret_key = os.getenv("AUTH0_SECRET")
app.config.update(
    SESSION_TYPE="redis",
    SESSION_PERMANENT=True,
    SESSION_KEY_PREFIX="auth0:",
    SESSION_COOKIE_SECURE=False,
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SAMESITE="Lax",
)
Session(app)

3. 无需修改存储器实现

auth.py 中的 FlaskSessionStateStore 和 FlaskSessionTransactionStore 可直接复用，无需任何更改。Flask-Session 会透明地将 flask.session 的后端从 Cookie 切换为 Redis，而存储器仍像之前一样继续使用 flask.session 接口。

路由代码完全一致 —— 与无状态部署相比，无需任何代码变更。

常见错误

核心 SDK 方法

所有方法均为异步：

相关技能

• auth0-express — 适用于带登录/登出会话的服务器渲染 Express Web 应用
• auth0-fastify — 适用于基于会话鉴权的 Fastify Web 应用
• auth0-cli — 从终端管理 Auth0 资源

速查参考

ServerClient 配置：

auth0 = ServerClient(
    domain=os.getenv("AUTH0_DOMAIN"),                    # 必需
    client_id=os.getenv("AUTH0_CLIENT_ID"),              # 必需
    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),      # 必需
    secret=os.getenv("AUTH0_SECRET"),                    # 必需（加密密钥）
    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),        # 必需
    state_store=FlaskSessionStateStore(secret=secret),   # 必需
    transaction_store=FlaskSessionTransactionStore(secret=secret),  # 必需
    authorization_params={"scope": "openid profile email"},  # 推荐
)

路由保护模式：

user = await auth0.get_user()
if user is None:
    return redirect("/login")

环境变量：

• AUTH0_DOMAIN — 你的 Auth0 租户域名（例如 tenant.us.auth0.com）
• AUTH0_CLIENT_ID — 你的应用的 Client ID
• AUTH0_CLIENT_SECRET — 你的应用的 Client Secret
• AUTH0_SECRET — 加密及会话密钥
• AUTH0_REDIRECT_URI — 回调 URL（例如 http://localhost:5000/callback）

详细文档

• 配置指南 — 自动化配置脚本、环境变量设置、Auth0 CLI 使用说明
• 集成指南 — 受保护路由、调用外部 API、会话管理、错误处理
• API 参考 — 完整的 ServerClient API、配置选项、存储器实现细节、安全说明

参考资料

• auth0-server-python PyPI 页面
• Auth0 Flask 快速入门指南
• Flask 官方文档