在 Teams 中的 SSO 身份验证故障排除

下面是有关 SSO 的问题和问题列表,以及如何解决这些问题。

支持 Microsoft Graph


1. 图形 API 是否在 Postman 中工作?
可以将 Microsoft Graph Postman 集合与 Microsoft Graph API 配合使用。

有关详细信息,请参阅结合使用 Postman 和 Microsoft Graph API


2. 图形 API 是否在 Microsoft Graph 资源管理器中工作?
是的,图形 API 在 Microsoft Graph 资源管理器中工作。

有关详细信息,请参阅 Graph 浏览器


错误消息及其处理方式


1. 错误:缺少同意。
当Microsoft Entra ID 收到访问 Microsoft Graph 资源的请求时,它会检查应用用户或租户管理员是否同意此资源。 如果没有用户或管理员的同意记录,Microsoft Entra ID 会向 Web 服务发送错误消息。

例如,代码必须告知客户端 (,例如,在 403 禁止访问响应的正文中,) 如何处理错误:

  • 如果选项卡应用需要 Microsoft Graph 仅管理员可以为其授予同意的范围,则代码应生成错误。
  • 如果用户只能许可所需的范围,则代码应回退到用户身份验证备用系统。

2.错误:缺少范围 (权限) 。
此错误仅在开发过程中出现。

若要处理此错误,服务器端代码应向客户端发送 403 禁止访问响应。 它应将错误记录到控制台或将其记录在日志中。


3.错误:Microsoft Graph 的访问令牌中的受众无效。
服务器端代码应向客户端发送 403 禁止访问响应,以便向用户显示消息。 建议它还应将错误记录到控制台,或将其记录在日志中。

4.错误:主机名不得基于已拥有的域。
可以在以下两种方案之一中收到此错误:
  1. 自定义域不会添加到Microsoft Entra ID。 若要将自定义域添加到 Microsoft Entra ID 并对其进行注册,请按照 将自定义域名添加到 Entra ID Microsoft 过程进行操作。 然后,按照步骤再次 配置访问令牌的范围
  2. 未使用 Microsoft 365 租户中的管理员凭据登录。 以管理员身份登录 Microsoft 365。

5.错误:返回的访问令牌中未收到用户主体名称 (UPN) 。
可以在 Entra ID Microsoft添加 UPN 作为可选声明。

有关详细信息,请参阅 向应用提供可选声明访问令牌


6.错误:Teams SDK 错误:resourceDisabled。
若要避免此错误,请确保在 Microsoft Entra 应用注册和 Teams 客户端中正确配置应用程序 ID URI。

有关应用程序 ID URI 的详细信息,请参阅“公开 API”。


7.错误:运行选项卡应用时出现一般错误。
当在 entra ID Microsoft 中所做的一个或多个应用配置不正确时,可能会出现一般错误。 若要解决此错误,请检查代码中配置的应用详细信息和应用清单 (以前称为 Teams 应用清单) 是否与 entra ID Microsoft 中的值匹配。

下图显示了在 Entra ID Microsoft 配置的应用详细信息示例。

Microsoft Entra ID 中的应用配置值

检查以下值在 Microsoft Entra ID、客户端代码和应用清单之间是否匹配:

  • 应用 ID:在 Microsoft Entra ID 中生成的应用 ID 在代码和应用清单文件中应相同。 检查应用清单架构中的应用 ID 是否与 Entra ID Microsoft 中的 Application (客户端) ID 匹配。

  • 应用机密:在应用后端配置的应用机密应与 Entra ID Microsoft 中的客户端凭据 匹配。 还应检查客户端密码是否已过期。

  • 应用程序 ID URI:代码和应用清单文件中的应用 ID URI 应与 Entra ID Microsoft 中的应用程序 ID URI 匹配。

  • 应用权限:检查你在作用域中定义的权限是否与应用要求一样。 如果是这样,请检查他们是否已在访问令牌中授予用户。

  • 管理员同意:如果任何范围都需要管理员同意,请检查是否已向用户授予特定作用域的同意。

此外,检查发送到选项卡应用的访问令牌,以验证以下值是否正确:

  • 受众 (aud) :检查令牌中的应用 ID 是否正确,如Microsoft Entra ID 中所述。
  • 租户 ID (tid):检查令牌中提到的租户是否正确。
  • 用户标识 (preferred_username) :根据当前用户想要访问的范围,检查用户标识是否与访问令牌请求中的用户名匹配。
  • 作用域 (scp) :检查请求访问令牌的作用域是否正确,以及Microsoft Entra ID 中定义。
  • Microsoft Entra 版本 1.0 或 2.0 (ver) :检查Microsoft Entra 版本是否正确。

可以使用 JWT 检查令牌。

机器人 SSO 令牌错误


令牌交换失败。
如果存在令牌交换失败,请使用以下代码:
{​​ 
    "status": "<response code>", 
    "body": 
    {​​ 
        "id":"<unique Id>", 
        "connectionName": "<connection Name on the bot (from the OAuth card)>", 
        "failureDetail": "<failure reason if status code is not 200, null otherwise>" 
    }​​ 
}​​

若要了解令牌交换无法触发同意提示时的机器人行为,请参阅以下步骤:

注意

不需要用户执行任何操作,因为当令牌交换失败时,机器人会执行操作。

  1. 客户端开始与触发 OAuth 方案的机器人对话。

  2. 机器人将 OAuth 卡片发送回客户端。

  3. 客户端在向应用用户显示 OAuth 卡之前截获它。 它会检查它是否包含 属性 TokenExchangeResource

  4. 如果该属性存在,则客户端会向机器人发送 TokenExchangeInvokeRequest。 客户端必须具有用户的可交换令牌。 此令牌必须是 Azure AD v2 令牌,其受众必须与 属性相同 TokenExchangeResource.Uri

  5. 客户端使用以下代码向机器人发送调用活动:

    {
        "type": "Invoke",
        "name": "signin/tokenExchange",
        "value": 
        {
            "id": "<any unique Id>",
            "connectionName": "<connection Name on the skill bot (from the OAuth card)>",
            "token": "<exchangeable token>"
        }
    }
    
  6. 机器人处理 TokenExchangeInvokeRequest 并将 TokenExchangeInvokeResponse 返回给客户端。 客户端必须等到它收到 TokenExchangeInvokeResponse

    {
        "status": "<response code>",
        "body": 
        {
            "id":"<unique Id>",
            "connectionName": "<connection Name on the skill bot (from the OAuth card)>",
            "failureDetail": "<failure reason if status code is not 200, null otherwise>"
        }
    }
    
  7. 如果 TokenExchangeInvokeResponsestatus200,则客户端不会显示 OAuth 卡片。 请参阅正常流程图像。 对于任何其他 status 或如果未收到 TokenExchangeInvokeResponse,客户端会向用户显示 OAuth 卡片。 请参阅回退流程图像。 如果存在任何错误或未满足的依赖项(如用户同意),此活动可确保 SSO 流回退到正常的 OAuthCard 流程。

    注意

    在 Teams Web 客户端中,密码提示不会显示,因为浏览器中有活动Microsoft Entra 会话,该会话用于身份验证和获取令牌。 在 Teams 桌面客户端中,出现密码提示,因为桌面客户端没有任何要共享的Microsoft Entra 会话,并且系统要求登录。

另请参阅

Microsoft Entra ID 中应用程序属性的安全最佳做法