azure-auth

Azure Auth 提供了一套将 Microsoft Entra ID（原 Azure AD）身份验证接入 React SPA 与 Cloudflare Workers 的全栈模式。

一、用途 该方案用于为 React 单页应用提供基于 Microsoft Entra ID 的登录与令牌获取能力，并在 Cloudflare Workers 后端对请求携带的 JWT 进行校验，从而保护 API 路由。

二、主要能力

1. 前端登录：使用 @azure/msal-react@5.0.2 与 @azure/msal-browser@5.0.2，采用 Authorization Code + PKCE 流程，获取 access_token 与 id_token。
2. 受保护路由：通过 useMsal、useIsAuthenticated 与 InteractionStatus 判断登录状态并触发登录重定向。
3. 令牌获取：优先使用 acquireTokenSilent 静默获取，遇到 InteractionRequiredAuthError 时回退到 acquireTokenRedirect 交互式登录。
4. 后端校验：在 Cloudflare Workers 中使用 jose@6.1.3 校验 JWT，支持 JWKS 缓存（默认 1 小时）。
5. Worker 中间件：从 Authorization 头提取 Bearer token，校验失败返回 401，成功后将用户信息传递给受保护路由。
6. 多租户支持：单租户使用具体 tenant ID 作为 authority；多租户使用 common 或 organizations，并在后端根据 token 中的 tid 动态校验 issuer。

三、使用方式

1. 安装依赖：前端执行 npm install @azure/msal-react @azure/msal-browser；后端执行 npm install jose。
2. Azure 门户配置：在 Microsoft Entra ID → App registrations 新建注册，重定向 URI 设为 http://localhost:5173（SPA 类型），记录 Application (client) ID 与 Directory (tenant) ID；在 Authentication 中启用 Access tokens 与 ID tokens 并添加生产重定向 URI；在 API permissions 中添加 User.Read（Microsoft Graph），必要时授予管理员同意。
3. 前端配置：在 msal-config.ts 中设置 clientId、authority、redirectUri、postLogoutRedirectUri、cache（cacheLocation 与 storeAuthStateInCookie）以及 loginRequest、apiRequest 的 scopes。
4. 初始化：在组件树外创建 PublicClientApplication 实例，调用 initialize()，使用 getAllAccounts() 设置活动账户，并通过 MsalProvider 包裹应用。
5. 后端校验：先请求 openid-configuration 获取 jwks_uri，再用 jose.createRemoteJWKSet 创建远程 JWKS，最后用 jose.jwtVerify 校验 issuer 与 audience。
6. 环境变量：前端使用 VITE_AZURE_CLIENT_ID、VITE_AZURE_TENANT_ID；后端在 wrangler.jsonc 的 vars 中配置 AZURE_TENANT_ID、AZURE_CLIENT_ID。

四、适用场景 适用于需要以 Microsoft Entra ID 作为身份提供方的 React SPA，以及部署在 Cloudflare Workers 上、需要校验 Entra ID 令牌的 API 服务。单租户模式适合企业内应用，多租户模式适合允许任意 Azure AD 租户用户登录的应用。

五、限制与注意事项

1. MSAL.js 无法在 Cloudflare Workers 中运行，后端必须使用 jose。
2. Azure AD 的 JWKS 不在标准的 .well-known/jwks.json 路径，必须先获取 openid-configuration 再取 jwks_uri。
3. SPA 刷新令牌固定有效期为 24 小时，无法延长，过期后需重新登录（AADSTS700084）。
4. Safari/Edge 需要开启 storeAuthStateInCookie；iOS 18 Safari 即使允许第三方 Cookie 仍可能失败，属已知浏览器限制，暂无解决办法，建议改用 Chrome 或桌面浏览器。
5. React Router v6 可能剥离包含认证响应的 hash 片段，需使用自定义 NavigationClient。
6. setActiveAccount 不会触发 React 重渲染，需借助状态强制更新。
7. 版本与生命周期：MSAL v4→v5 迁移（2026 年 1 月）；Azure AD B2C 于 2025 年 5 月 1 日起停止新客户注册，2026 年 3 月 15 日 P2 对所有客户停用，现有 B2C 客户支持至 2030 年 5 月；ADAL 已于 2025 年 9 月完全退役。
8. 资料未提供收费、价格与具体平台支持范围等信息。