用途:在服务端校验 Microsoft Entra ID(Azure AD)访问令牌,通过 jose 与租户 JWKS 端点验证令牌并基于声明推导身份,适用于新增或审查 Entra/Azure AD JWT 校验逻辑的场景。
主要能力与必须满足的约束:accessTokenAcceptedVersion 必须为 2,可用 az ad app show --id <appId> --query api.requestedAccessTokenVersion 确认;受众需同时接受裸 clientId 与 api://<clientId> 两种形式;拒绝既无 scp 也无 roles 的令牌(此类校验会误把 ID 令牌当访问令牌接受);身份应取自 preferred_username(UPN)而非 email,因为 Entra v2 访问令牌常缺失 email 声明;GUID/oid 比较必须大小写不敏感;必须在拒绝非 ASCII 输入之后再做大小写折叠(例如 U+212A 的 Kelvin 符号经 toLowerCase 会折叠为 ASCII k,可能造成标识符碰撞)。
被跳过时的后果:跳过前两条会让合法令牌被拒;跳过第三条会导致静默的权限提升;跳过第四条会造成部分真实用户身份解析失败;跳过第五、六条会导致身份混淆,或将合法用户永久锁死,或允许一个标识符冒充另一个。
参考实现位置(资料给出):~/code/quick/src/auth/entra.ts 为原始 TypeScript 实现(verifyEntraToken、mapClaims),约束 1-4 以行内注释形式存在;~/code/mykai/portal/lib/entra.mjs 为直接 JS 移植;~/code/mykai/portal/lib/identity.mjs 额外包含约束 5-6(bindIdentity、netidFromUpn)以及针对畸形/缺失历史记录的 fail-closed 处理和按 epoch 绑定 oid 的逻辑。
限制:上述约束为跨使用方反复出现的规范,而非共享包,需按每个使用方重新生成实现;调试时报错通常只是笼统的 issuer/audience 不匹配;具体安装命令、价格与平台支持情况资料未提供。