使用服务主体认证Microsoft Teams API及Cmdlets失败排查

针对你遇到的401未授权问题，以下是核心排查点：

• 确认使用应用权限而非委派权限
  Teams语音相关的PowerShell cmdlet和API均需后台无用户上下文的操作，必须配置应用权限（Application Permissions），而非委派权限。且必须由全局管理员或对应角色管理员完成管理员同意（用户同意无效）。例如：

  • 操作用户企业语音/号码分配：需添加Microsoft Graph > VoiceUser.ReadWrite.All、User.Read.All应用权限
  • 调用呼叫队列API：需添加Microsoft Graph > CallQueue.ReadWrite.All或Teams特定API的对应应用权限

• 检查权限范围覆盖所有操作
  针对你用到的两类操作分别核对：

  • Get-CSOnlineUser：需确保应用拥有Microsoft Graph > User.Read.All（应用权限）或Skype for Business Online > CsUser.Read.All应用权限
  • 呼叫队列API（https://api.interfaces.records.teams.microsoft.com/Teams.VoiceApps/callqueues）：需确认已添加该API对应的应用权限（可在Entra ID应用的“API权限”中搜索Teams相关API，添加对应读写权限）

• 验证令牌的受众与权限声明
  用jwt.ms解析获取到的令牌，检查：

  • aud字段是否匹配目标API的资源URI（例如呼叫队列API的受众应为https://api.interfaces.records.teams.microsoft.com，Graph API为https://graph.microsoft.com）
  • 存在roles字段（应用权限的标识），且包含你配置的权限名称。如果只有scp字段，说明用了委派权限，不符合后台操作要求

• 为应用分配必要的Entra ID角色
  部分Teams语音操作仅靠API权限不足，需给应用的服务主体分配管理员角色：

  • 登录Entra ID门户，进入“角色和管理员”，找到Teams语音管理员、用户管理员或全局管理员（按需分配最小权限）
  • 添加应用的服务主体为该角色的成员

• 确认PowerShell认证方式正确
  使用应用身份连接Teams PowerShell时，必须使用以下命令格式（二选一）：

  # 证书认证
  Connect-MicrosoftTeams -ApplicationId "<你的应用ID>" -TenantId "<租户ID>" -CertificateThumbprint "<证书指纹>"
  # 客户端密钥认证
  Connect-MicrosoftTeams -ApplicationId "<你的应用ID>" -TenantId "<租户ID>" -ClientSecret "<客户端密钥>"
  

  若误用用户身份的连接命令，会因无有效应用权限返回401

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