FastAPI-Azure-Auth 角色权限实战:5 步实现基于角色的访问控制(RBAC)

FastAPI-Azure-Auth 角色权限实战:5 步实现基于角色的访问控制(RBAC)【免费下载链接】fastapi-azure-authEasy and secure implementation of Azure Entra ID (previously AD) for your FastAPI APIs B2C, single- and multi-tenant support.项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-azure-authFastAPI-Azure-Auth 是目前在 FastAPI 项目中接入 Azure Entra ID(原 Azure AD)认证与授权最流行的开源方案之一。当你的 API 不再满足于能登录就行,而是需要区分管理员、普通用户、只读访客时,基于角色的访问控制(RBAC)就派上了用场。本文用 5 个实战步骤,带你用 FastAPI-Azure-Auth 完成从 Azure 角色配置到 FastAPI 代码校验的完整 RBAC 闭环,全程无需手写 JWT 解析逻辑,安全又省心。 想跟着动手?先克隆示例项目:git clone https://gitcode.com/gh_mirrors/fa/fastapi-azure-auth一、RBAC 原理:角色到底存在哪里?基于角色的访问控制(RBAC)的核心思路是:把谁能做什么从代码里抽离出来,交给角色定义。在 FastAPI-Azure-Auth 的体系里,用户登录后,Azure Entra ID 会把用户拥有的角色写进访问令牌(access token)的roles声明(claim)中。打开源码 user.py,可以看到User模型里有一个roles: list[str]字段——这正是 RBAC 判断的数据源。你的任务就两步:在 Azure 侧定义角色并分配给用户;在 FastAPI 侧校验user.roles是否包含所需角色。接下来就是完整的 5 步实战。二、5 步实现 RBAC 实战第 1 步:注册应用,拿到凭据首先进入 Azure 门户,创建一个应用注册(App registration)。这一步是后续所有配置的地基,请记住页面上展示的Application (client) ID和Directory (tenant) ID,后面写代码要用。提示:单租户应用选 Accounts in this organizational directory only,多租户或 B2C 场景请按官方文档 single-tenant/azure_setup.mdx 与 b2c/azure_setup.mdx 配置账户类型。第 2 步:在 Manifest 中定义角色角色的定义不靠点击按钮,而是通过编辑应用清单(Manifest)完成。进入应用的Manifest页面,找到 JSON 中的appRoles数组,添加一个管理员角色,例如:appRoles: [ { allowedMemberTypes: [User], description: 管理员,可访问管理接口, displayName: AdminUser, id: 11111111-2222-3333-4444-555555555555, isEnabled: true, value: AdminUser } ]保存后,这个角色名AdminUser就会以字符串形式出现在持有该角色的用户令牌的roles声明中,与你后面在 FastAPI 代码里写的判断值一一对应。第 3 步:把用户分配给角色角色定义好了,接下来把具体用户挂到角色上。回到应用注册的Overview(概览)页面,找到下方的 Managed application 链接,点击进入企业应用程序(Enterprise application)管理页:进入Users and groups(用户和组),添加用户并选择刚才定义的AdminUser角色,点击 Assign 完成分配。之后该用户重新登录获取的新令牌中,就会携带roles: [AdminUser]。⚠️ 细节提醒:如果通过组分配角色,用户必须是该组的直接成员,嵌套组不生效。完整操作截图可参考官方文档 locking_down_on_roles.mdx。第 4 步:FastAPI 中接入认证方案回到代码侧。先安装并初始化 FastAPI-Azure-Auth:在 main.py 中配置好swagger_ui_oauth2_redirect_url和swagger_ui_init_oauth,然后在依赖文件 dependencies.py 中创建认证方案:from fastapi_azure_auth.auth import SingleTenantAzureAuthorizationCodeBearer azure_scheme SingleTenantAzureAuthorizationCodeBearer( app_client_idsettings.APP_CLIENT_ID, tenant_idsettings.TENANT_ID, scopes{ fapi://{settings.APP_CLIENT_ID}/user_impersonation: user_impersonation, }, )启动服务后,Swagger 文档右上角会出现绿色的Authorize按钮,点击即可通过 Azure 登录并获取令牌:第 5 步:编写角色校验依赖,完成 RBAC这是实现基于角色的访问控制的核心一步:写一个自己的依赖函数,把它当成azure_scheme的加强版来用。参考官方示例,新建security.py:from typing import Annotated from fastapi import Depends from fastapi_azure_auth.exceptions import ForbiddenHttp from fastapi_azure_auth.user import User async def validate_is_admin_user(user: User Depends(azure_scheme)) - None: if AdminUser not in user.roles: raise ForbiddenHttp(User is not an AdminUser) AdminUser Annotated[User, Depends(validate_is_admin_user)]然后在需要保护的接口上直接注入:app.get(/admin/items) def read_admin_items(user: AdminUser): return {message: 只有 AdminUser 角色才能访问}这样,普通用户即使登录成功,也会因为令牌中缺少AdminUser角色而收到 403 Forbidden,完美实现细粒度的 RBAC 控制。三、进阶:多角色判断与测试技巧多角色与复杂判断user.roles是一个列表,天然支持多角色场景。比如管理员或运营都能删数据,只需判断集合是否有交集:if not (set(user.roles) {AdminUser, Operator}): raise ForbiddenHttp(权限不足)用依赖覆盖写单元测试FastAPI-Azure-Auth 的依赖注入设计让测试非常简单:利用app.dependency_overrides替换azure_scheme,直接注入一个带指定roles的User对象即可。官方测试文档 testing.mdx 和测试代码 tests/single_tenant/test_single_tenant.py 提供了可直接套用的写法:fastapi_app.dependency_overrides[azure_scheme] mock_normal_user总结至此,你已经用 FastAPI-Azure-Auth 完成了从 Azure 角色定义、用户分配到 FastAPI 代码校验的完整 RBAC 链路。回顾一下 5 步:注册应用、Manifest 定义角色、分配用户、接入认证、编写角色依赖——每一步都清晰可查,代码量却不到 20 行。更重要的是,令牌验证、密钥轮换、签发者校验这些安全细节全部由库内部处理,你只需专注业务。快去你的 FastAPI 项目里实践一下吧!【免费下载链接】fastapi-azure-authEasy and secure implementation of Azure Entra ID (previously AD) for your FastAPI APIs B2C, single- and multi-tenant support.项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-azure-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考