SharePoint加载项CSOM执行KQL搜索触发未授权异常求助

问题特征 #

• 2021年1月29日起，调用CSOM搜索接口执行KQL查询时抛出System.UnauthorizedAccessException
• 对照验证：使用new SharePointOnlineCredential(用户名, 密码)的认证流程可正常完成搜索；通过TokenHelper.GetClientContextWithAccessToken获取的ClientContext实例执行搜索时触发未授权错误

根因定位 #

该异常为2021年1月29日SharePoint Online服务端规则更新导致的兼容性问题：

• 服务端将搜索类CSOM接口的OAuth权限校验逻辑从原有的站点级权限校验链路中完全拆分，不再自动继承加载项的站点操作权限。此前仅为加载项配置的站点级FullControl权限，从该更新节点起不再满足搜索接口的调用要求
• 用户名密码的认证流程走用户委托的全量权限校验链路，不受本次细粒度权限拆分的影响，因此可保持正常运行

排查步骤 #

• 检查AccessToken的权限声明：将通过TokenHelper流程生成的AccessToken解码，查看payload中的权限角色段，确认是否缺失搜索接口要求的应用权限项
• 检查服务主体的权限配置：定位Azure AD中对应加载项绑定的服务主体，确认API权限列表中是否存在SharePoint Online下的应用类型Search.Query.All权限，且已完成全局管理员的同意操作
• 检查加载项的授权范围：如果是通过_layouts/15/appregnew.aspx创建的传统低信任加载项，确认原有授权是否仅绑定了单站点操作权限，未覆盖租户级搜索接口的调用授权
• 检查ClientContext的目标URL：确认搜索请求的路由端点与加载项的授权范围匹配，避免请求路由到未授权的站点管理路径触发校验失败

修复操作 #

• 为对应服务主体补充缺失的搜索应用权限：在应用的API权限配置面板，添加SharePoint Online的应用类型搜索权限，完成管理员同意
• 重新完成加载项授权：移除原有的单站点权限绑定，通过站点集的_layouts/15/appinv.aspx页面为加载项授予租户级搜索结果查询的对应权限，不要仅选择“对当前站点拥有完全控制”的授权范围
• 清理应用端的AccessToken本地缓存，重新生成带最新权限声明的访问令牌，避免旧的无权限令牌被复用触发错误
• 权限修改完成后存在10-15分钟的服务端同步延迟，若立即测试仍报错可等待同步完成后重新验证

常见踩坑点 #

• 站点级别的FullControl权限无法自动覆盖搜索接口的调用要求，需单独配置独立的搜索权限项
• 非交互的加载项场景下，委托类型的搜索权限无法通过服务端校验，必须使用应用类型的权限配置
• 不要混淆旧版SharePoint加载项的权限模型与Azure AD企业应用的权限模型，两类应用的搜索权限校验逻辑从2021年1月更新后保持一致，均不继承站点操作权限

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