使用 Microsoft Graph 权限和范围扩展选项卡应用

  • 项目

可以使用 Microsoft Graph 扩展选项卡应用，以允许其他用户权限，例如查看应用用户配置文件、阅读邮件等。 应用必须请求特定权限范围才能在应用用户同意后获取访问令牌。

图形范围（如 User.Read 或 Mail.Read）指示应用可以从 Teams 用户帐户访问的内容。 需要在授权请求中指定范围。 本文将指导你完成为 Teams 选项卡应用配置 Microsoft Graph 权限和范围的步骤。

在 Microsoft Entra ID 中配置 API 权限

可以在 Microsoft Entra ID 中为应用配置其他 Graph 范围。 这些是委派权限，由需要登录访问的应用使用。 登录的应用用户或管理员必须首先同意他们。 此后，选项卡应用在调用 Microsoft Graph 时可以代表已登录用户同意。

建议对已登录用户使用委托的权限。 如果应用程序不需要已登录用户，请考虑使用应用程序权限，也称为仅应用访问方案。 只有管理员才能授予对应用程序权限的同意。 有关详细信息，请参阅 应用程序权限。

配置 API 权限

  1. 打开在 Azure 门户中注册的应用。

  2. 从左窗格中选择“ 管理>API 权限 ”。

    屏幕截图显示了“应用权限”菜单选项。

    将显示 API 权限页面。

  3. 选择“+ 添加权限”以添加 Microsoft 图形 API权限。

    屏幕截图显示了“应用权限”页。

    将显示“请求 API 权限”页。

  4. 选择 Microsoft Graph。

    屏幕截图显示了“请求 API 权限”页。

    显示 Graph 权限的选项。

  5. 选择“ 委托的权限 ”或“ 应用程序权限” 可分别查看委派权限列表或应用程序权限。

    屏幕截图显示了委派的权限。

  6. 选择应用的相关权限，然后选择“添加权限”。

    屏幕截图显示了“添加权限”选项。

    还可以在搜索框中输入权限名称来查找。

    浏览器上弹出一条消息，指出权限已更新。

    屏幕截图显示针对更新的权限显示的消息。

    添加的权限显示在 API 权限 页中。

    屏幕截图显示了配置了 API 权限的示例。

    你现在已使用 Microsoft Graph 权限配置应用。

为不同平台配置身份验证

根据要以应用为目标的平台或设备，可能需要其他配置，例如重定向 URI、特定身份验证设置或特定于平台的详细信息。

注意

  • 如果选项卡应用尚未获得 IT 管理员同意，则应用用户需要在第一次在不同的平台上使用你的应用时提供同意。
  • 如果在选项卡应用上启用了单一登录 (SSO) ，则不需要隐式授予。

只要 URL 唯一，就可以为多个平台配置身份验证。

为平台配置身份验证

  1. 打开在 Azure 门户中注册的应用。

  2. 从左窗格中选择“管理>身份验证”。

    用于对平台进行身份验证的屏幕截图。

    将显示 平台配置 页。

  3. 选择 + 添加平台。

    屏幕截图显示了用于添加平台的选项。

    将显示“配置平台”页。

  4. 选择要为选项卡应用配置的平台。 可以从 Web 或 单页应用程序中选择平台类型。

    用于选择 Web 平台的屏幕截图。

    可以为特定平台类型配置多个平台。 确保重定向 URI 对于你配置的每个平台是唯一的。

    将显示“配置 Web”网页。

    注意

    根据所选的平台，配置会有所不同。

  5. 输入平台的配置详细信息。

    用于配置 Web 平台的屏幕截图。

    1. 输入重定向 URI。 URI 应是唯一的。
    2. 输入前通道注销 URL。
    3. 选择要Microsoft Entra ID为应用发送的令牌。

  6. 选择“配置”。

    平台已配置并显示在“平台配置”页中。

获取 MS Graph 的访问令牌

需要获取 Microsoft Graph 的访问令牌。 为此，可以使用Microsoft Entra代表 (OBO) 流。

单一登录 (SSO) 的当前实现仅限于用户级权限，而用户级权限不适用于进行 Graph 调用。 若要获取进行 Graph 调用所需的权限和范围，SSO 应用必须实现自定义 Web 服务，以将从 Teams JavaScript 库收到的令牌交换为包含所需范围的令牌。 可以使用 Microsoft 身份验证库 (MSAL) 从客户端提取令牌。

在 Microsoft Entra ID 中配置 Graph 权限后，需要从 Teams 客户端获取令牌 ID，然后将其与服务器端令牌交换。

从 Teams 客户端获取令牌 ID

下面是从 Teams 客户端获取令牌 ID 的示例：

microsoftTeams.authentication.getAuthToken().then((result) => {
    //result contains the id token
            console.log(result);
        })

将令牌 ID 与服务器端令牌交换

下面是使用 MSAL 从 Teams 客户端提取访问令牌的 OBO 流示例：

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(<"Client id">)
                                                .WithClientSecret(<"Client secret">)
                                                .WithAuthority($"https://login.microsoftonline.com/<"Tenant id">")
                                                .Build();
            try
            {
                var idToken = <"Client side token">;
                UserAssertion assert = new UserAssertion(idToken);
                List<string> scopes = new List<string>();
                scopes.Add("https://graph.microsoft.com/User.Read");
                // Acquires an access token for this application (usually a Web API) from the authority configured in the application.
                var responseToken = await app.AcquireTokenOnBehalfOf(scopes, assert).ExecuteAsync();
                return responseToken.AccessToken.ToString();
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }

如果需要访问 Microsoft Graph 数据，请将服务器端代码配置为：

  1. 验证访问令牌。 有关详细信息，请参阅验证访问令牌。
  2. 通过调用 Microsoft 标识平台来启动 OAuth 2.0 代理流，该平台包括访问令牌、有关用户的一些元数据，以及选项卡应用的凭据（其应用 ID 和客户端密码）。 Microsoft 标识平台返回可用于访问 Microsoft Graph 的新访问令牌。
  3. 使用新的令牌从 Microsoft Graph 获取数据。
  4. 如有必要，请在 MSAL.NET 中使用令牌缓存序列化来缓存多个新的访问令牌。

重要

  • 作为安全性的最佳做法，请始终使用 服务器端代码进行 Microsoft Graph 调用 或其他需要传递访问令牌的调用。 这有助于保护令牌免受截获或泄露的侵害。 请勿将 OBO 令牌返回给客户端，因为这会使客户端能够直接调用 Microsoft Graph。
  • 在 Microsoft Entra ID 中注册的两个单独应用需要每个应用的单独令牌。 使用 OBO 流 启用应用之间的通信。
  • 不要使用 notifySuccess result 将令牌信息返回到父页。 使用 localStorage 保存令牌并通过 传递项密钥 notifySuccess。

应用可以从租户管理员全局获取 Graph 权限的许可，也可以按用户单独获得许可。

从租户管理员

代表组织同意的一种简单方法是获取管理员同意。

从用户

使用 Microsoft Teams JavaScript 客户端库 (TeamsJS) 身份验证 功能请求其他用户同意时，请记住以下注意事项：

若要在个人选项卡中实现 SSO 身份验证，请执行以下步骤：

  1. 必须使用 getAuthToken() MICROSOFT ENTRA OBO 流在服务器端交换检索到的令牌，才能访问其他图形 API。 确保为此交换使用 Microsoft Entra v2 终结点。

  2. 首次尝试为用户执行令牌交换时，如果Microsoft Entra拒绝交换令牌，可能是因为用户未同意向应用授予对用户数据的权限。 在这些情况下，交换失败并出现 invalid_grant 或 interaction_required 错误。 invalid_grant错误的示例包括需要同意或auth_code、断言或刷新令牌过期、吊销、格式不正确或缺失时。 interaction_required的示例包括何时需要多重身份验证或公司设备注册。

  3. 如果交换因 或 interaction_required 错误而invalid_grant失败，则必须提示用户同意。 由于用户交互只能从客户端进行，因此服务器需要向客户端应用返回需要同意的指示。 然后，可以使用用户界面 (UI) 请求应用用户授予其他许可。 UI 必须包含触发Microsoft Entra同意对话框的按钮。

  4. 若要请求用户同意你的应用访问其数据，必须在 prompt=consentquery-string-parameter 中包含 属性才能Microsoft Entra ID。

    • 使用 ?prompt=consent&scope={scopes} 而不是 ?scope={scopes}
    • 确保 属性 {scopes} 包括提示用户输入的所有范围。 例如，Mail.Read 或 User.Read。

    若要处理选项卡应用的增量同意，请参阅 增量和动态用户同意。

  5. 应用用户授予更多权限后，重试 OBO 流以访问其他 Graph API。 有关详细信息，请参阅 Teams 个人选项卡 SSO 身份验证 示例代码。

无效授予异常后进行 OBO 调用时的争用条件

如果用户未授予这些范围的Microsoft Entra应用程序同意，则 OBO 调用失败invalid_grant或interaction_required出错。 此错误会通知你需要提示用户同意。

当用户已提供同意，而你尝试立即发出 OBO 呼叫时，有时Microsoft Entra ID传播此同意与发生 OBO 请求之间存在争用条件。 这可能会导致 OBO 调用失败，出现相同的 invalid_grant 或 interaction_required 错误。

如果应用程序不知道此行为，它可能会多次请求用户同意。 最佳做法是构建有意义的等待和重试机制，以避免这种不理想的用户体验。

等待和重试机制必须跟踪用户是否同意所需的范围。 如果包含 OBO 请求的 API 调用失败并出现上述错误，但用户已同意，请避免向用户显示同意提示。 相反，请在重试 API 调用之前等待一段时间。 通常，Microsoft Entra ID会在三到五秒内发送同意。 在一个 示例应用程序中，我们最多重试三次，每次重试之间的等待时间是两倍，从一秒的等待开始。

如果在三到五次尝试之后，OBO 流仍然失败，则用户可能尚未同意所有必需的范围，并且你可能必须提示他们再次同意。

此方法有助于减少多次提示用户同意的可能性。

代码示例

示例名称 说明 C# Node.js
选项卡Microsoft Entra SSO 适用于选项卡的 Microsoft Teams 示例应用Microsoft Entra SSO，它使用 OBO 流调用 Graph API。 View View

另请参阅