FastAPI-Azure-Auth 单租户认证完整教程一步步配置 Azure Entra ID 应用注册【免费下载链接】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想给 FastAPI 接口加上企业级登录认证却不知道从哪里下手FastAPI-Azure-Auth 正是为此而生的开源库它让Azure Entra ID原 Azure AD单租户认证变得异常简单。本文是一份面向新手的完整教程手把手带你完成 Azure Entra ID 应用注册的每一步配置并把认证无缝接入你的 FastAPI 应用最终在 Swagger 文档里一键登录、安全调用受保护的 API。全程无需纠结复杂的 OAuth2 协议细节跟着做就能跑通为什么选择单租户认证模式在动手配置 Azure Entra ID 应用注册之前先花 30 秒想清楚你的应用场景单租户Single tenant只允许你自己组织Azure 租户内的账号登录适合企业内部系统、私有 API配置最简单、最安全 ✅多租户允许任何组织的账号登录适合 SaaS 产品对外提供服务B2C面向消费者的社交登录场景作为初学者推荐从单租户认证开始后续随时可以迁移到多租户模式。FastAPI-Azure-Auth 在 auth.py 中分别提供了SingleTenantAzureAuthorizationCodeBearer、MultiTenantAzureAuthorizationCodeBearer和B2CMultiTenantAzureAuthorizationCodeBearer三个类用法高度一致先掌握单租户认证其他模式一通百通。准备工作安装库并获取示例项目首先安装依赖需要Python 3.11 及以上版本uv add fastapi-azure-auth如果想参考完整的真实项目结构可以克隆官方示例仓库内含 demo_project/main.py 等完整代码git clone https://gitcode.com/gh_mirrors/fa/fastapi-azure-auth 完整的官方图文说明位于仓库的 azure_setup.mdx 和 fastapi_configuration.mdx本文是它们的精华提炼版。接下来进入正题开始配置 Azure Entra ID 应用注册。整个流程需要创建两个应用注册一个给后端 API一个给 OpenAPISwagger文档使用。第一步创建后端 API 的 Azure Entra ID 应用注册登录 Azure 门户依次进入Microsoft Entra ID → App registrations点击New registration创建新的应用注册。这里有两个关键配置Name给应用起一个合适的名字比如my-awesome-API用户登录授权时会看到这个名字Supported account types选择Accounts in this organizational directory onlySingle tenant这就是单租户认证模式点击Register完成创建后端 API 的应用注册就搞定啦第二步将访问令牌版本切换为 v2创建完成后进入应用注册的Manifest页面。在 JSON 清单中找到requestedAccessTokenVersion字段把它的值从null改为2然后点击Save保存。⚠️ 这个变更在 Azure 侧生效需要一点时间所以官方教程特意把它放在最开始执行好让它在后续步骤完成时已经就绪。新项目一律使用 v2 令牌。第三步记录应用 ID 与租户 ID回到应用注册的Overview概览页面这里有两个关键信息需要复制保存Application (client) ID应用客户端 IDDirectory (tenant) ID租户 ID建议把它们存到项目的.env环境变量文件中方便后续统一管理TENANT_ID你的租户ID APP_CLIENT_ID后端API的应用ID OPENAPI_CLIENT_ID稍后创建的OpenAPI应用ID第四步添加 user_impersonation 应用作用域现在进入应用注册左侧菜单的Expose an API点击 Add a scope。系统会提示设置Application ID URI直接保留默认推荐值形如api://xxxxxxxx-xxxx-xxxx点击Save and continue继续。随后填写作用域信息Scope nameuser_impersonation表示以用户身份访问 APIWho can consent选择Admins and usersAdmin consent display name / description如 Access API as user / Allows the app to access the API as the userUser consent display name / description如 Access API as you / Allows the app to access the API as you创建完成后作用域全名即为api://{APP_CLIENT_ID}/user_impersonation这个值稍后会在 FastAPI 配置中用到务必记住。第五步为 OpenAPI 文档创建专用应用注册为了让 Swagger 文档也能安全登录需要为它单独创建一个应用注册。再次前往App registrations新建注册Name与后端同名并加上- OpenAPI后缀如my-awesome-API - OpenAPISupported account types同样是Single tenantRedirect URI选择平台Single-Page Application (SPA)地址填写http://localhost:8000/oauth2-redirect创建完成后同样执行两步操作在Manifest中把requestedAccessTokenVersion改为2然后在Overview中复制它的 Application (client) ID填入.env文件的OPENAPI_CLIENT_ID。第六步授权 OpenAPI 应用访问后端 API最后一步很关键进入 OpenAPI 应用注册的API permissions点击 Add a permission选择My APIs标签页找到刚才创建的后端 API。勾选user_impersonation作用域并点击Add a permission。至此Azure 侧的配置全部完成 下面把它接入 FastAPI。快速配置把认证接入你的 FastAPI 应用首先在 FastAPI 应用初始化时配置 OpenAPI 的 OAuth2 参数核心在 demo_project/main.py 中app FastAPI( swagger_ui_oauth2_redirect_url/oauth2-redirect, swagger_ui_init_oauth{ usePkceWithAuthorizationCodeGrant: True, clientId: settings.OPENAPI_CLIENT_ID, }, )接着创建认证实例推荐单独放在 demo_project/api/dependencies.py 这类依赖文件中from fastapi_azure_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, }, )最后在路由上声明依赖一行代码即可保护你的 APIapp.get(/, dependencies[Security(azure_scheme, scopes[user_impersonation])]) async def root(): return {message: Hello World} 可选优化在应用启动时通过await azure_scheme.openid_config.load_config()预加载 OpenID 配置避免首次登录时的额外等待。OpenID 配置的完整实现细节见 openid_config.py。验证效果在 Swagger 中体验完整登录流程启动应用访问http://localhost:8000/docs。此时 Swagger 页面右上角会出现一个绿色的Authorize按钮点击Authorize在弹出的授权窗口中检查授权方式为 Azure AD - PKCE, Single-tenant即单租户认证 PKCE 授权码流程勾选user_impersonation作用域Client secret 保持留空PKCE 流程不需要它点击 Authorize 后会跳转到微软登录页面完成登录并同意权限请求回到 Swagger 后再次调用受保护的 API就能看到 200 成功响应了常见问题与排错提示redirect URL 报错多半是用了127.0.0.1:8000而不是localhost:8000请保持一致401 Unauthorized检查 Manifest 中的requestedAccessTokenVersion是否已改为2以及作用域名是否与配置完全一致CORS 报错确保在 FastAPI 中配置了CORSMiddleware并把http://localhost:8000加入允许来源忘记配置重定向地址应用注册的 Redirect URI 必须与swagger_ui_oauth2_redirect_url完全匹配结语至此你已经完成了 Azure Entra ID 应用注册的全部配置并成功为 FastAPI 应用接入了安全可靠的单租户认证 整个过程并不复杂创建两个应用注册、切换令牌版本、添加作用域、配置 API 权限最后在代码里组装SingleTenantAzureAuthorizationCodeBearer即可。如果想继续进阶还可以研究多租户认证、B2C 模式或参考仓库 tests/single_tenant 中的测试用例加深理解。快去动手实践吧祝你的 API 从此安全无忧【免费下载链接】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），仅供参考