Better Auth 接入 Azure AD 指南：3 步配好单租户、多租户与 CIAM 登录-平芜编程栈

Better Auth 接入 Azure AD 指南：3 步配好单租户、多租户与 CIAM 登录

【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth

给企业客户交付 SaaS，对方 HR 要求员工用公司账号登录，可没人想啃 OAuth2 文档。Better Auth 直接给了你一条 Azure AD（Microsoft Entra ID）登录通道：填好 clientId 和密钥，租户怎么选、令牌怎么验、头像从哪拉，都在底层处理好了，几分钟就能跑通。

⚡ 3 分钟跑通 Azure AD 登录

整个流程就三步：装包、在 Azure 门户建应用、写配置。

先装依赖（具体版本以官方文档为准）：

npm install better-auth

接着在 Azure 门户的 Entra ID → App registrations 里新建一个应用：记下 Application (client) ID，再到 Certificates & secrets 生成一条客户端密码；把 Redirect URI 填成你应用里 Microsoft 的回调地址，本地开发通常是http://localhost:3000/api/auth/callback/microsoft，线上换成真实域名。

配置端只留三行最关键的东西，可选项后面按场景补：

import { betterAuth } from "better-auth"; export const auth = betterAuth({ socialProviders: { microsoft: { clientId: process.env.MICROSOFT_CLIENT_ID, clientSecret: process.env.MICROSOFT_CLIENT_SECRET, }, }, });

跑起来后，登录页点一下 "Continue with Microsoft"，浏览器会跳到微软登录页，用户输完公司账号回来，你的后端已经把令牌换好、用户落库，整条链路就通了。

🔍 底层帮你拦了哪些协议细节

你不写一行 OAuth 代码，是因为下面这几件它都办了。

令牌这一头：它拿 Microsoft 的公钥端点去验返回的 ID 令牌签名，再核对颁发者、受众和签发时间；多租户场景还会额外查一次租户绑定，别家租户的令牌想混进来也进不了。

流程这一头：走的是标准授权码流程，内部自带 PKCE 的 code verifier 和 state 校验，CSRF 和中间人这两类坑不用你手动去堵。

资料这一头：令牌里的 name、email、picture 会被解析成本地用户字段，头像还会去 Graph API 拉一张按你指定尺寸裁好的图，而不是把一大段 base64 硬塞进会话。默认它会请求 openid、profile、email、User.Read、offline_access 这几项 scope，够用；要更多权限用 scope 选项追加。

🧩 按场景挑一种租户写法

单租户。只允许某一个 Azure 租户的人登录，把 tenantId 填成该租户的 GUID 即可，用户换到别的租户就会被挡在门外：

microsoft: { clientId: "你的 clientId", clientSecret: "你的 clientSecret", tenantId: "72f988bf-86f1-41af-91ab-2d7cd011db47", // 指定租户 GUID }

多租户（默认）。tenantId 不填就是 common，任何租户都能进；如果你只想收企业账号、挡住个人微软账号，就写 organizations：

microsoft: { clientId: "你的 clientId", clientSecret: "你的 clientSecret", tenantId: "organizations", // 仅企业/学校账号 }

CIAM（面向客户）。面向 C 端的客户身份场景要换 authority，tenantId 保持不动：

microsoft: { clientId: "你的 clientId", clientSecret: "你的 clientSecret", authority: "https://<tenant-id>.ciamlogin.com", }

自定义字段映射。用 mapProfileToUser 把额外字段搬进你的用户表；注意账号身份锚点 oid 是固定的，这里改不了它，只能映射本地字段：

microsoft: { clientId: "你的 clientId", clientSecret: "你的 clientSecret", mapProfileToUser: (profile) => ({ email: profile.verified_primary_email?.[0], }), }

✅ 上线前的 4 项安全检查

回调地址逐字对齐。Azure 里填的 Redirect URI 和你代码里的回调必须一模一样，差一个斜杠都会直接报回调错误。
密钥走环境变量。clientSecret 别写死进代码，进了版本库就等于半公开。
邮箱别默认当已验证。Entra 对托管账号默认不下发 email_verified，要区分已验证邮箱，得在应用注册里把 email 配成 optional claim，或改用 verified_primary_email。
头像体积。微软把头像以 base64 返回，大图可能撑爆 HTTP 头，必要时在 mapProfileToUser 里上传到自己存储或直接丢弃。

⚠️ 登录时的 3 个高频坑

回调直接报错 / state 不匹配。多半是本地和 Azure 两边的 redirect URI 没对齐，把两个地址逐字核对一遍通常就好。
登录成功但用户没有 email。这是 Entra 对托管账号的默认行为，去应用注册把 email 加为 optional claim，或在 mapProfileToUser 里用 verified_primary_email 兜底。
升级后老账号对不上、冒出重复用户。1.7 把身份锚点从 sub 换成了 oid，按升级指南做一次一次性迁移，别直接放生产流量。