PublicClientApplicationBuilder静默获令牌抛MsalUiRequiredException(授权过期)

问题核心 #

使用PublicClientApplication获取微软邮箱授权后，约20小时出现MsalUiRequiredException（提示Grant is expired），无法静默续期令牌，根源在于未请求长期离线访问权限，且默认公共客户端刷新令牌有效期仅约24小时。

关键解决方案 #

1. 添加offline_access权限范围 #

微软要求必须包含offline_access scope才能获取可续期的长期刷新令牌，否则刷新令牌到期后无法自动续期。修改scope定义：

// 确保包含邮件读取权限和离线访问权限
var _scopes = new[] { "Mail.Read", "offline_access" };

2. 确认Azure AD应用注册配置 #

• 在Azure门户的应用注册中，进入「认证」页面，添加「移动和桌面应用」平台，设置正确的重定向URI（如http://localhost或你的回调地址）。
• 开启「允许公共客户端流」（在「认证」->「高级设置」中设为「是」），确保PublicClientApplication能正常获取刷新令牌。

3. 优化令牌缓存持久化 #

默认内存缓存重启后会丢失，且无法长期保存刷新令牌。需使用持久化缓存（如文件、数据库）确保刷新令牌被持久化存储：

// 示例：使用文件缓存存储令牌
var cachePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), "msal_mail_cache.bin");
var storageProps = new StorageCreationPropertiesBuilder(cachePath, Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData))
    .Build();
var cacheHelper = await MsalCacheHelper.CreateAsync(storageProps);
cacheHelper.RegisterCache(pca.UserTokenCache);

4. 简化静默获取令牌的代码 #

静默获取时无需添加CORS相关HTTP头（Origin、Access-Control-Allow-Origin），这些仅适用于前端交互请求，后端静默请求会干扰令牌获取流程：

refresh = await pca
    .AcquireTokenSilent(_scopes, account)
    .WithTenantId("common")
    .ExecuteAsync();

5. 异常处理逻辑 #

捕获MsalUiRequiredException时，区分是否为刷新令牌真正过期：

try
{
    refresh = await pca.AcquireTokenSilent(_scopes, account).WithTenantId("common").ExecuteAsync();
}
catch (MsalUiRequiredException ex)
{
    // 检查异常原因，仅当确实需要用户交互时才引导授权
    if (ex.ErrorCode == "invalid_grant" && ex.Message.Contains("Grant is expired"))
    {
        // 此处可记录日志，或触发重新授权流程
        throw; // 或处理为引导用户重新点击授权按钮
    }
}

原理说明 #

添加offline_access后，微软会返回可续期的刷新令牌，有效期最长可达90天，且每次使用刷新令牌获取新访问令牌时，会自动续期刷新令牌（延长有效期）。若未添加该scope，刷新令牌仅为短期有效（约24小时），到期后必须重新授权。

内容的提问来源于stack exchange，提问作者Avrohom