SuperAPI AI 工具集

troubleshooting-authentication

安全与审计

查看项目

更新于 10-16 00:30

技能介绍

用途:该技能用于排查 Microsoft Foundry Web 应用的认证问题,涵盖 MSAL、JWT 与 Entra ID 相关故障,例如调试 401 错误、令牌失效、MSAL 配置异常和凭据获取失败。

架构:浏览器经 MSAL.js(PKCE 流程)获取带 Chat.ReadWrite 作用域的 JWT;前端以 JWT Bearer 令牌调用后端;后端使用 ManagedIdentityCredential 访问 Foundry Agent Service。

常见问题与修复:/api/* 返回 401 通常是令牌缺少作用域,需确认令牌含 Chat.ReadWrite;本地出现 ManagedIdentityCredential 错误多为环境设置错误,应设 ASPNETCORE_ENVIRONMENT=Development;令牌弹窗被拦截需允许 localhost 弹窗;静默获取令牌失败通常是缺少缓存令牌,由 useAuth 回退到弹窗方式。

后端:JWT 校验同时接受两种受众格式,即客户端 ID 与 api://{ClientId}。凭据策略在开发环境使用 ChainedTokenCredential(AzureCliCredential 与 AzureDeveloperCliCredential),以支持 azd auth login;生产环境使用 ManagedIdentityCredential。本地开发需先执行 az login 或 azd auth login。采用链式凭据可避免 DefaultAzureCredential 不可预测的快速失败模式,便于调试。

前端:MSAL 模式为先尝试 acquireTokenSilent,失败则回退 acquireTokenPopup。

调试步骤:用 https://jwt.ms 查看令牌内容;确认作用域含 Chat.ReadWrite;确认受众匹配客户端 ID 或 api://{clientId};在 Azure 门户核对 Entra 应用重定向 URI。

环境变量:前端 .env.local 配置 VITE_ENTRA_SPA_CLIENT_ID 与 VITE_ENTRA_TENANT_ID;后端 .env 配置 AzureAd__ClientId 与 AzureAd__TenantId;可运行 azd up 重新生成 Entra 应用与 .env 文件。

限制:其他平台、收费与效果等资料暂未提供。