zopyx-fastapi-auth

一个为FastAPI设计的具有偏好的认证和授权系统。

特性

• 基于RDBMS的用户数据库（通过sqlmodel支持几乎所有数据库）
• 一个命令行工具，用于添加、删除用户
• 角色和权限
• 基于权限或角色的FastAPI端点保护
• 全面测试，全面测试覆盖率，全面遵守mypy，运行时参数检查
• 一个用于任意认证/授权的插件系统（需要实现一个类和一个方法）

状态

• 在生产中

需求

• 支持Python 3.10-3.12（不支持Python 3.9或更低版本，目前不支持Python 3.13）

使用示例

• 见demo_app.py

概念

本包基于以下概念构建

角色和权限

角色分配给用户。用户可以拥有一个或多个角色。权限定义了特定的访问范围，例如查看条目、删除条目、更新条目。一个角色可以拥有多个权限。因此，用户可以拥有多个角色，一个角色也可以拥有多个权限。

如何定义权限的示例

from fastapi_auth.permissions import Permission

VIEW_PERMISSION = Permission(name="view", description="View permission")
EDIT_PERMISSION = Permission(name="edit", description="Edit permission")
DELETE_PERMISSION = Permission(name="delete", description="Delete permission")

角色是这样定义的

from fastapi_auth.permissions import  Role

ADMIN_ROLE = Role(
    name="Administrator",
    description="Admin role",
    permissions=[VIEW_PERMISSION, EDIT_PERMISSION, DELETE_PERMISSION],
)
USER_ROLE = Role(
    name="User",
    description="User role",
    permissions=[VIEW_PERMISSION, EDIT_PERMISSION],
)
VIEWER_ROLE = Role(
    name="Viewer",
    description="Viewer role",
    permissions=[VIEW_PERMISSION],
)

此外，所有角色都必须在全球ROLES_REGISTRY中注册

from fastapi_auth.roles import ROLES_REGISTRY

ROLES_REGISTRY.register(ADMIN_ROLE)
ROLES_REGISTRY.register(USER_ROLE)
ROLES_REGISTRY.register(VIEWER_ROLE)

FastAPI应用程序的端点可以通过一个权限或一个或多个角色进行保护。

在这个示例中，/admin端点仅对具有管理员角色的已认证用户可访问

# This is an endpoint that requires the user to be authenticated.  In this case,
# the user must have the ADMIN_ROLE role.  It is also possible to require a
# permission instead.  Use the Protected dependency to require authentication.
# An unauthenticated request as ANONYMOUS_USER will be rejected.
@app.get("/admin")
def admin(user: User = Depends(Protected(required_roles=[ADMIN_ROLE]))):
    return {"user": user}

您还可以使用权限来保护端点

from fastapi_auth.dependencies import Protected

@app.get("/admin")
def admin2(user: User = Depends(Protected(required_permission=VIEW_PERMISSION))):
    return {"user": user}

另一个选项是使用自定义回调方法来保护路由，该方法对于给定的 Request 和 User 返回 True 或 False。

from fastapi_auth.dependencies import Protected

def my_check(request: Request, user: User) -> bool:
    # perform some checks based on request and/or user....
    return True # or False

@app.get("/admin")
def admin3(user: User = Depends(Protected(required_checker=my_check))):
    return {"user": user}

请注意，传递给回调的 user 对象要么是已认证的用户，要么是 ANONYMOUS_USER。根据进一步的标准授权已认证的用户是回调的责任。

安装会话中间件

为了对您的应用程序进行测量，您需要调用 install_middleware(app) 并传入您的自定义 FastAPI app 对象。

from fastapi_auth.auth_routes import install_middleware

# Your FastAPI app
app = FastAPI()

# install the session middleware
install_middleware(app)

# add endpoints for authentication examples
app.mount("/auth", auth_router)

# add static files (for demo login form)
app.mount("/static", StaticFiles(directory="static"), name="static")

用户管理

目前，fastapi-auth 将用户账户存储在 SQL 数据库中。有一个名为 fastapi-auth-user-admin 的实用程序，可以通过命令行管理用户账户。没有支持（将来也不会支持）通过网页管理界面管理用户账户。可以使用 AUTH_DB_URI 环境变量配置数据库连接。

添加用户

fastapi-auth-user-admin add <username> <password> "Role1,Role2..."

删除用户

fastapi-auth-user-admin delete <username>

列出用户

fastapi-auth-user-admin list-users 

设置用户密码

fastapi-auth-user-admin set-password <username> <new-password> 

环境变量

AUTH_DEFAULT_KEY

AUTH_DEFAULT_KEY 用作加密用户会话信息的密钥。强烈建议设置此值而不是依赖于代码中使用的默认密钥。

AUTH_DB_URI

AUTH_DB_URI 必须设置为 SQL 数据库。 zopyx-fastapi-auth 在内部使用 sqlmodel，该库使用 SQLAlchemy 并支持所有数据库（请参阅 https://docs.sqlalchemy.org.cn/en/20/core/engines.html#database-urls）。

使用当前工作目录内的 SQLite 数据库 users.db 的示例

export AUTH_DB_URI=sqlite:///users.db

AUTH_LOG_FILENAME

默认情况下，该模块将日志输出到控制台和到 fastpi_auth.log。您可以通过设置 AUTH_LOG_FILENAME 环境变量使用不同的文件名。

内部实现

该实现基于 starlette-session （https://pypi.ac.cn/project/starlette-session/）中间件。用户信息通过基于签名的基于 cookie 的 HTTP 会话存储。会话信息可读但不能修改。加密密钥可以通过环境变量配置。

使用包含的迷你演示应用程序入门

安装

检查代码库并使用 pip 或 uv 安装它

python3.12 -m venv .venv
source .venv/bin/activate
pip3 install -e .

或

uv venv -p python3.12
source .venv/bin/activate
uv pip install -e .

创建演示用户

fastapi-auth-user-admin add admin admin Administrator

这将创建一个密码为 admin 的 admin 用户。

运行演示服务

uvicorn fastapi_auth.demo_app:app

登录到演示应用程序

访问 http://localhost:8000/auth/login 并以 admin/admin 登录。

成功登录后

可插入的认证器

此模块提供了一个灵活的架构，允许在您的 FastAPI 应用程序中使用多个认证和授权后端。例如，您可以配置认证系统使用默认的关系型数据库管理系统（RDBMS）用户管理，并补充一个轻量级目录访问协议（LDAP）的附加插件。

示例

Authenticator 需要实现一个 authenticate(request: Request) 方法。此方法应从登录请求中提取登录参数并返回一个 Users 对象。认证器需要注册到 AUTHENTICATOR_REGISTRY。认证器的执行顺序由它们的 position 参数确定。一个 position 为 0 表示认证器是第一个使用的。较高的 position 值表示较低的优先级。

from fastapi import Request
from fastapi.authenticator_registry import Authenticator, AUTHENTICATOR_REGISTRY
from fastapi.users import User 

class MyAuthenticator(Authenticator):

    async def authenticate(request: Request) -> User:

        # extract credentials from request
        username = request.form....
        password = request.form....

        # perform authentication against your own authentication system
        user_data = my_backend.authenticate_user(username, password)
        
        return User(name=user_data["name"], roles=[...])

AUTHENTICATOR_REGISTRY.add_authenticator(MyAuthenticator(), 0)

提供的路由

《demo_app.py》应用程序展示了/auth/login和/auth/logout路由的集成。您可以在auth_routes.py中找到这些路由的实现。此代码可自定义，允许您根据特定需求进行适配，因为它包含一些与日志记录和UI集成相关的预配置决策。登录过程的核心在于login_post()函数。由于其简单性和简洁性，您应该能够轻松地根据需求调整登录流程。

作者

Andreas Jung info@zopyx.com