为选项卡应用启用 SSO

  • 项目

借助 Teams 中的单一登录 (SSO) ，应用用户可以使用 Teams 访问选项卡应用。 使用 Microsoft 或 Microsoft 365 帐户登录到 Teams 后，应用用户无需再次登录即可使用你的应用。 通过Microsoft Entra ID授予访问权限的任何设备上的应用用户都可以使用你的应用。

本部分将介绍以下内容：

  1. SSO 用户体验：Teams 为应用用户提供真正的 SSO 体验。 应用用户无需再次登录即可使用你的应用。
  2. 运行时 Teams 中的 SSO：选项卡应用在运行时与Microsoft Entra ID交互，以便对应用用户进行一次性身份验证和授权。
  3. 为选项卡应用启用 SSO：实现在选项卡应用中启用 SSO 所涉及的任务。

Teams 中的 SSO 用户体验

应用用户使用个人 Microsoft 帐户或 Microsoft 365 帐户登录到 Teams。 可以利用此帐户，并使用 SSO 对应用用户进行身份验证和授权。

屏幕截图显示了团队选项卡应用中的 SSO 用户体验。

  • Teams 对其应用用户的身份进行身份验证并存储。
  • 选项卡应用使用已由 Teams 验证的应用用户的存储标识。
  • 应用用户需要同意 Teams 使用标识访问选项卡应用。
  • 应用用户可以在 Web、桌面或移动客户端上访问应用。

可在此处查看选项卡应用中 SSO 的用户体验示例：

图形表示形式显示选项卡应用中 SSO 的用户体验。

使用 SSO 增强用户体验

下面是应用用户通过 SSO 体验获得的内容：

  • Teams 从 Microsoft Entra ID 获取当前应用用户的访问令牌。 与Microsoft Entra ID的这种交互对应用用户不可见。 它转换为获取应用访问权限，而无需离开 Teams 环境。
  • 应用用户只需在多租户环境中同意。 如果应用用户和应用驻留在同一租户中，则应用用户无需同意使用该应用。
  • 首次同意 Teams 后，应用用户可以使用你的应用，而无需进一步的同意，即使在任何其他设备上也是如此。 因此，它提供了更好的用户体验。
    • 或者，租户管理员可以代表应用用户授予同意。 在此方案中，当租户管理员同意租户中的应用用户时，根本不需要提示应用用户同意。 这意味着应用用户看不到同意对话框，并且可以无缝访问应用。
  • Teams 会预提取访问令牌，以提高 Teams 环境中应用的性能和加载时间。
  • 应用用户无需记住或记录多个密码即可在 Teams 环境中访问和使用应用。

现在，让我们看看在运行时后端发生的情况，以在 Teams 中实现 SSO 体验。

运行时 Teams 中的 SSO

通过获取当前登录的 Teams 应用用户的访问令牌，在选项卡应用中实现 SSO。 此过程涉及选项卡应用客户端和服务器、Teams 客户端和Microsoft Entra ID。 在此交互期间，应用用户必须同意使用 Teams 标识在多租户环境中获取访问令牌。

下图显示了当 Teams 应用用户尝试访问选项卡应用时 SSO 的工作原理：

屏幕截图显示了选项卡 SSO 进程流及其工作原理。

# 交互 这是怎么回事
1 选项卡应用→ Teams 客户端 选项卡应用对 JavaScript 进行调用 getAuthToken()，告知 Teams 获取访问令牌。
2 Teams 客户端→ Microsoft Entra ID Teams 请求Microsoft Entra终结点，用于基于 Teams 标识的当前应用用户的访问令牌。
3 Microsoft Entra ID →同意表单 如果当前应用用户是第一次使用选项卡应用，则如果应用需要访问一些受保护的数据，Teams 会显示请求提示以表示同意。 应用用户 (或管理员) 必须同意 Teams 使用应用用户的 Teams 标识从Microsoft Entra ID获取访问令牌。
或者，有一个请求提示来处理升级身份验证，例如双因素身份验证。
4 Microsoft Entra ID → Teams 客户端 Microsoft Entra ID将访问令牌发送到 Teams 客户端。 令牌是 JWT) (JSON Web 令牌，其验证工作原理与大多数标准 OAuth 流中的令牌验证一样。 Teams 代表你缓存令牌，以便将来调用 getAuthToken() 返回缓存的令牌。
5 Teams 客户端→选项卡应用客户端 Teams 将选项卡访问令牌作为 getAuthToken() 调用返回的结果对象的一部分发送到选项卡。
6 客户端和服务器) 之间的选项卡应用 ( 使用 JavaScript 在选项卡应用程序中分析令牌，以提取所需的信息，例如用户的电子邮件地址。 返回到选项卡应用的令牌既是访问令牌又是标识令牌。

有关详细信息，请参阅 添加代码以在选项卡应用中启用 SSO 和 添加代码以在机器人应用中启用 SSO。

重要

  • getAuthToken() 仅对一组有限的用户级 API（即电子邮件、配置文件、offline_access、OpenId）的许可有效。 它不用于其他 Graph 范围，如 User.Read 或 Mail.Read。 有关建议的解决方法，请参阅 使用 Microsoft Graph 权限扩展应用。
  • getAuthToken匿名用户的 失败，因为他们不是Microsoft Entra帐户。

选项卡是 Teams 感知的网页。 若要在选项卡应用内托管的网页中启用 SSO，请添加 Teams JavaScript 客户端库 并调用 microsoftTeams.initialize()。 初始化后，调用 microsoftTeams.getAuthToken() 以获取应用的访问令牌。

用于启用 SSO 的用例

可以在 Teams 中为所有支持Microsoft Entra ID作为标识提供者的应用启用 SSO。 除了使用 SSO 对选项卡应用中的应用用户进行身份验证外，还可以使用它实现跨 Teams 的无缝访问。

可以使用 SSO API 对应用用户进行身份验证的一些方案包括：

  • 如果要对 Teams 选项卡应用中的应用用户进行身份验证，SSO API 允许应用用户在 Teams 中使用应用，而无需进行其他身份验证。 根据应用用户的 Teams 标识，可以从Microsoft Entra ID获取他们的访问令牌。
  • 如果你的应用在机器人、选项卡、消息扩展或自适应卡片中使用对话框 (称为 TeamsJS v1.) x 中的任务模块，则可以使用 SSO API 对应用用户进行身份验证。
  • 还可以使用 SSO API 对想要访问 Stageview 的应用用户进行身份验证，而无需再次验证。

提示

还可以使用 SSO API 在嵌入 Web 内容的 对话框中 对应用用户进行身份验证。

若要在运行时实现 SSO，请将应用配置为启用 SSO 以对应用用户进行身份验证和授权。

为 Teams 选项卡应用启用 SSO

本部分介绍为 Teams 应用实现 SSO 所涉及的任务。 这些任务与语言和框架无关。

若要为 Teams 选项卡应用启用 SSO，请执行以下操作：

       屏幕截图显示了为选项卡启用 SSO 的步骤。

  1. 使用 Microsoft Entra ID 配置应用：创建Microsoft Entra应用以生成应用 ID 和应用程序 ID URI。 若要生成访问令牌，请配置范围并授权受信任的客户端应用程序。
  2. 添加代码：添加代码以处理访问令牌，将此令牌发送到授权标头中的应用服务器代码，并在收到访问令牌时对其进行验证。
  3. 更新 Teams 应用清单：使用Microsoft Entra ID上生成的应用 ID 和应用程序 ID URI 更新 Teams 客户端应用清单，以允许 Teams 代表你的应用请求访问令牌。

iOS 上的第三方 Cookie

iOS 14 更新后，Apple 默认阻止所有应用的 第三方 Cookie 访问。 因此，在其频道或聊天选项卡中使用第三方 Cookie 进行身份验证的应用以及个人应用将无法在 Teams iOS 客户端上完成其身份验证工作流。 若要符合隐私和安全要求，必须转为使用基于令牌的系统，或在用户身份验证工作流程中使用第一方 Cookie。

Teams 移动客户端支持

对于 Teams 移动版，支持 SSO 的客户端版本为：

  • 适用于 Android 的 Teams（1416/1.0.0.2020073101 及更高版本）
  • 适用于 iOS 团队（版本：2.0.18 及更高版本）
  • Teams JavaScript 库 (版本：1.11 及更高版本) ，用于 SSO 在会议侧面板中工作

为获得 Teams 的最佳体验，请使用最新版本的 iOS 和 Android。

分步指南

使用以下分步指南来启用 Teams 应用的 SSO：

最佳做法

下面列出了最佳做法：

  • 仅在需要时调用访问令牌：仅在需要访问令牌时调用 getAuthToken() 。 当应用用户访问选项卡应用或使用需要应用用户验证的特定函数时，可以调用它。
  • 不要在客户端代码上存储访问令牌：不要在应用的客户端代码中缓存或存储访问令牌。 Teams 客户端 (缓存访问令牌，如果访问令牌) 过期，则请求新令牌。 这可确保 Web 应用不会意外泄漏令牌。
  • 对 Microsoft Graph 调用使用服务器端代码：始终使用服务器端代码进行 Microsoft Graph 调用，或者使用需要传递访问令牌的其他调用。 从不将 OBO 令牌返回到客户端，以允许客户端直接调用 Microsoft Graph。 这有助于保护令牌免受截获或泄露的侵害。 有关详细信息，请参阅 具有 Microsoft Graph 权限和范围的“扩展”选项卡应用。

已知限制

  • 目前，Teams 中的 SSO 仅支持 OAuth 2.0 令牌。 它不支持 SAML 令牌。
  • 不支持每个应用多个域。 有关详细信息，请参阅 为组织生成的自定义应用 (LOB 应用) 。
  • iframed 或中转应用不支持重定向。 如果使用重定向 API 或使用弹出 (window.parent!==window) => trueAPI，请确保在窗口的顶部框架中使用 MSAL.js。

后续步骤

在 Microsoft Entra ID 中注册选项卡应用程序

另请参阅