Office 加载项中的身份验证和授权概述

  • 项目

默认情况下，Office 加载项允许匿名访问，但你可以要求用户登录以后再使用Microsoft 帐户、Microsoft 365 教育版或工作帐户或其他公共帐户的外接程序。 此任务被称为“用户身份验证”，因为它让加载项能够知道用户的身份。

您的外接程序还可以获得用户同意访问其 Microsoft Graph 数据 (例如 Microsoft 365 配置文件、OneDrive 文件和 SharePoint 数据) 或其他外部源（如 Google、Facebook、LinkedIn、SalesForce 和 GitHub）中的数据。 此任务称为外接程序 (或应用) 授权，因为它是正在授权的 加载项 ，而不是用户。

用于身份验证和授权的关键资源

本文档介绍如何构建和配置 Office 加载项，以成功实现身份验证和授权。 但是，所述的许多概念和安全技术超出了本文档的范围。 例如，此处未介绍常规安全概念，如 OAuth 流、令牌缓存或标识管理。 本文档也不记录任何特定于 Microsoft Azure 或Microsoft 标识平台的信息。 如果需要这些方面的信息，建议参考以下资源。

SSO 方案

用户使用单一登录(SSO)非常方便，因为他们只需登录一次即可使用 Office。 他们无需单独登录到加载项。 并非所有版本的 Office 都支持 SSO，因此仍需要使用 Microsoft 标识平台实现替代登录方法。 有关支持的 Office 版本的详细信息，请参阅 标识 API 要求集

通过 SSO 获取用户标识

通常，外接程序仅需要用户的标识。 例如，你可能只想对加载项进行个性化设置，并在任务窗格中显示用户的名称。 或者，你可能希望唯一 ID 将用户与数据库中的数据关联。 只需从 Office 获取用户的访问令牌即可实现此目的。

若要通过 SSO 获取用户标识，请调用 getAccessToken 方法。 此方法返回一个访问令牌，该令牌也是一个标识令牌，其中包含对当前已登录用户唯一的多个声明，包括 preferred_username、name、sub和oid。 有关这些属性的详细信息，请参阅 Microsoft 标识平台 ID 令牌。 有关 getAccessToken 返回的令牌示例，请参阅示例访问令牌。

如果用户未登录，Office 将打开一个对话框，并使用Microsoft 标识平台请求用户登录。 然后，此方法将返回访问令牌，或在用户无法登录时弹出错误。

在需要存储用户数据的方案中，请参阅 Microsoft 标识平台 ID 令牌，了解如何从令牌获取值以唯一标识用户。 使用该值在你维护的用户表或用户数据库中查找用户。 使用数据库来用户用户首选项或用户帐户状态等用户相关信息。 由于使用的是 SSO，因此用户不会单独登录到加载项，因此无需为用户存储密码。

开始使用 SSO 实现用户身份验证之前，请确保已完全熟悉 为 Office 加载项启用单一登录一文。

通过 SSO 访问 Web API

如果加载项具有需要授权用户的服务器端 API，请调用 getAccessToken 方法以获取访问令牌。 访问令牌提供对自己的 Web 服务器的访问权限， (通过 Microsoft Azure 应用注册) 进行配置。 在 Web 服务器上调用 API 时，还会传递访问令牌来授权用户。

以下代码演示如何构造对外接程序 Web 服务器 API 的 HTTPS GET 请求，以获取数据。 代码在客户端运行，例如在任务窗格中运行。 它首先通过调用 getAccessToken 获取访问令牌。 然后，它使用服务器 API 的正确授权标头和 URL 构造 AJAX 调用。

function getOneDriveFileNames() {

    let accessToken = await Office.auth.getAccessToken();

    $.ajax({
        url: "/api/data",
        headers: { "Authorization": "Bearer " + accessToken },
        type: "GET"
    })
        .done(function (result) {
            //... work with data from the result...
        });
}

下面的代码显示了上一个代码示例中 REST 调用的示例 /api/data 处理程序。 ASP.NET Web 为在服务器上运行的代码。 属性 [Authorize] 将要求从客户端传递有效的访问令牌，否则它会向客户端返回错误。

    [Authorize]
    // GET api/data
    public async Task<HttpResponseMessage> Get()
    {
        //... obtain and return data to the client-side code...
    }

通过 SSO 访问 Microsoft Graph

在某些情况下，不仅需要用户的标识，还需要代表用户访问 Microsoft Graph 资源。 例如，可能需要发送电子邮件，或代表用户在 Teams 中创建聊天。 可以通过 Microsoft Graph 完成这些操作和其他操作。 需要按照以下步骤操作：

  1. 通过 SSO 调用 getAccessToken 获取当前用户的访问令牌。 如果用户未登录，Office 将打开一个对话框，并使用Microsoft 标识平台登录用户。 用户登录后或者在用户已登录时，该方法会返回一个访问令牌。
  2. 将访问令牌传递到服务器端代码。
  3. 在服务器端，使用 OAuth 2.0 代理流 来交换访问令牌，以获得包含必要的委托用户标识和调用 Microsoft Graph 权限的新访问令牌。

注意

为获得最佳安全性以避免泄露访问令牌，请始终在服务器端执行代表流。 从服务器（而不是客户端）调用Microsoft Graph API。 不要将访问令牌返回到客户端代码。

在开始实现 SSO 以访问外接程序中的 Microsoft Graph 之前，请确保已完全熟悉以下文章。

还应至少阅读以下文章之一，这些文章将指导你构建 Office 外接程序以使用 SSO 和访问 Microsoft Graph。 即使不执行这些步骤，也包含有关实现 SSO 和代表流的有用信息。

非 SSO 方案

在某些情况下，你可能不想使用 SSO。 例如，可能需要使用不同的标识提供程序进行身份验证，而不是 Microsoft 标识平台。 此外，并非所有方案都支持 SSO。 例如，较旧版本的 Office 不支持 SSO。 在这种情况下，你需要回退到加载项的备用身份验证系统。

向 Microsoft 标识平台进行身份验证。

加载项可以使用作为身份验证提供程序的 Microsoft 标识平台登录用户。 登录用户后，可以使用Microsoft 标识平台向 Microsoft Graph 或 Microsoft 托管的其他服务授权加载项。 当 SSO 在 Office 不可用时，使用此方法作为备用登录方法。 此外，在某些情况下，你希望让用户单独登录到加载项，即使 SSO 可用;例如，如果希望他们选择使用与当前登录到 Office 的 ID 不同的 ID 登录到加载项。

请务必注意，Microsoft 标识平台不允许其登录页在 iframe 中打开。 当 Office 加载项在 Office web 版 中运行时，任务窗格是 iframe。 这意味着你需要使用通过 Office 对话框 API 打开的对话框打开登录页。 这会影响你使用身份验证帮助程序库的方式。 有关详细信息，请参阅使用 Office 对话框 API 进行身份验证。

有关使用 Microsoft 标识平台实现身份验证的信息，请参阅 Microsoft 标识平台(v2.0)概述。 该文档包含许多教程和指南，以及指向相关示例和库的链接。 正如使用 Office 对话框 API 进行身份验证中所述，你可能需要调整示例中的代码以在 Office 对话框中运行。

在不使用 SSO 的情况下访问 Microsoft Graph

可以通过从 Microsoft 标识平台获取Microsoft Graph 的访问令牌，以获取对加载项 Microsoft Graph 数据的授权。 无需依赖通过 Office (的 SSO，或者如果 SSO 失败或不受支持，) 即可执行此操作。 有关详细信息，请参阅 在没有 SSO 的情况下访问 Microsoft Graph，其中包含更多详细信息和示例链接。

访问非 Microsoft 数据源

借助 Google、Facebook、领英、SalesForce 和 GitHub 等热门在线服务，开发人员可授权用户访问自己在其他应用中的帐户。 这样，便可在 Office 加载项中添加这些服务。 要概述了解加载项可执行此操作的方法，请参阅在 Office 加载项中授权外部服务。

重要

在开始编码之前，请确定数据源是否允许其登录页在 iframe 中打开。 当 Office 加载项在 Office web 版 中运行时，任务窗格是 iframe。 如果数据源不允许其登录页在 iframe 中打开，则需要在使用 Office 对话框 API 打开的对话框中打开登录页。 有关详细信息，请参阅使用 Office 对话框 API 进行身份验证。

另请参阅