在 Office 加载项中启用单一登录 (SSO)

项目
02/01/2024

用户使用其个人 Microsoft 帐户或Microsoft 365 教育版或工作帐户登录到 Office。利用此功能并使用单一登录 (SSO) 验证用户并授权用户访问加载项，而无需用户重新登录。

显示加载项登录过程的图像。

运行时 SSO 的工作方式

以下关系图显示了 SSO 流程的工作方式。蓝色元素表示 Office 或 Microsoft 标识平台。灰色元素表示你编写的代码，包括客户端代码（任务窗格）和加载项的服务器端代码。

显示 SSO 流程的关系图。

在加载项中，JavaScript 代码调用 Office.js API getAccessToken。如果用户已登录到 Office，则 Office 主机将返回具有已登录用户声明的访问令牌。
如果用户未登录，Office 主机应用程序会打开一个对话框供用户登录。 Office 重定向到 Microsoft 标识平台以完成登录过程。
如果这是当前用户首次使用加载项，系统将提示他们同意。
Office 主机应用程序从当前用户的 Microsoft 标识平台请求访问令牌。
Microsoft 标识平台将访问令牌返回到 Office。 Office 将代表你缓存令牌，以便将来对 getAccessToken 的调用仅返回缓存的令牌。
Office 主机应用程序将访问令牌作为 getAccessToken 调用返回的结果对象的一部分返回到加载项。
该令牌既是访问令牌，也是身份令牌。可以将其用作身份令牌来分析和检查有关用户的声明，例如用户姓名和电子邮件地址。
或者，加载项可以使用令牌作为访问令牌，以向服务器端上的 API 发出经过身份验证的 HTTPS 请求。由于访问令牌包含身份声明，因此服务器可以存储与用户身份相关的信息；例如用户的首选项。

要求和最佳做法

不缓存访问令牌

从不在客户端代码中缓存或存储访问令牌。需要访问令牌时，始终调用 getAccessToken。 Office 将缓存访问令牌（或在过期时请求新的访问令牌。）这将有助于避免意外从加载项中泄露令牌。

为 Outlook 启用新式身份验证

如果使用的是 Outlook 加载项，请确保为 Microsoft 365 租户启用新式身份验证。有关如何执行此操作的信息，请参阅在 Exchange Online 中启用或禁用 Outlook 的新式身份验证。

实施回退身份验证系统

不应依赖 SSO 作为加载项的唯一身份验证方法。应实现备用身份验证系统，在某些错误情况下，加载项可以返回到该系统。例如，如果在不支持 SSO 的旧版 Office 上加载加载项，则 getAccessToken 调用将失败。

对于 Excel、Word 和 PowerPoint 加载项，你通常希望回退到使用 Microsoft 标识平台。有关详细信息，请参阅使用 Microsoft 标识平台进行身份验证。

对于 Outlook 加载项，建议使用回退系统。有关详细信息，请参阅应用场景：在 Outlook 外接程序中对服务实现单一登录。

你还可以使用用户表和身份验证系统，或者可以利用其中一个社交登录提供程序。有关如何使用 Office 插件进行此操作的详细信息，请参见授权 Office 加载项中的外部服务。

有关使用 Microsoft 标识平台作为回退系统的代码示例，请参阅 Office 加载项 NodeJS SSO 和 Office 加载项 ASP.NET SSO。

开发 SSO 加载项

此部分介绍了创建启用 SSO 的 Office 加载项所需完成的任务。此处介绍的这些任务独立于语言或框架。有关分步说明，请参阅：

向 Microsoft 标识平台注册加载项

若要使用 SSO，需要向 Microsoft 标识平台注册加载项。这将使 Microsoft 标识平台能够为加载项提供身份验证和授权服务。创建应用注册包括以下任务。

获取应用程序 (客户端) ID，以识别 Microsoft 标识平台中的加载项。
生成客户端密码，以在请求令牌时用作加载项的密码。
指定加载项所需权限。始终需要 Microsoft Graph“配置文件”和“OpenId”权限。根据加载项需要执行的操作，你可能需要其他权限。
向加载项授予 Office 应用程序信任。
使用默认范围 access_as_user 将 Office 应用程序预授权给加载项。

有关此过程的更多详细信息，请参阅向 Microsoft 标识平台注册使用 SSO 的 Office 加载项。

配置加载项

向加载项清单添加新标记。

<WebApplicationInfo> - 以下元素的父元素。
<ID> - 应用程序 (客户端) 向Microsoft 标识平台注册加载项时收到的 ID。有关详细信息，请参阅向 Microsoft 标识平台注册使用 SSO 的 Office 加载项。
<资源> - 加载项的 URI。这是你在向 Microsoft 标识平台注册加载项时使用的相同 URI（包括 api: 协议）。此 URI 的域部分必须与域（包括外接程序清单的“资源”>部分的 URL< 中使用的任何子域）匹配，并且 URI 必须以 Id> 元素中指定的<客户端 ID 结尾。
<Scopes> - 一个或多个 <Scope> 元素的父级。
<范围> - 指定加载项所需的权限。始终需要 profile 和 openID 权限，并且可能是唯一需要的权限。如果外接程序需要访问 Microsoft Graph 或其他 Microsoft 365 资源，则需要其他 <Scope> 元素。例如，对于 Microsoft Graph 权限，你可以请求 User.Read 和 Mail.Read 范围。在代码中用于访问 Microsoft Graph 的库可能需要其他权限。有关详细信息，请参阅向 Office 加载项中的 Microsoft Graph 授权。

对于 Word、Excel 和 PowerPoint 加载项，将标记添加到 <VersionOverrides ... xsi:type="VersionOverridesV1_0"> 部分的末尾。对于 Outlook 加载项，将标记添加到 <VersionOverrides ... xsi:type="VersionOverridesV1_1"> 部分的末尾。

下面是一个标注示例。

<WebApplicationInfo>
    <Id>5661fed9-f33d-4e95-b6cf-624a34a2f51d</Id>
    <Resource>api://addin.contoso.com/5661fed9-f33d-4e95-b6cf-624a34a2f51d</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>files.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

重要

如果外接程序由一个或多个管理员部署到其组织，则向清单添加新范围需要管理员同意更新。在授予同意之前，将阻止用户从外接程序中访问。

注意

如果不遵循 SSO 清单中的格式要求，则 AppSource 将拒绝加载项，直到其满足所需格式。

包括标识 API 要求集

若要使用 SSO，加载项需要标识 API 1.3 要求集。有关详细信息，请参阅 IdentityAPI。

添加客户端代码

将 JavaScript 添加到加载项，以执行以下操作：

调用 getAccessToken。
解析访问令牌或将其传递到加载项的服务器端代码。

以下代码显示了调用 getAccessToken 和分析用户名和其他凭据的令牌的简单示例。

注意

此示例只显式处理一种错误。有关更详细的错误处理的示例，请参阅 Office 加载项 NodeJS SSO 和 Office 加载项 ASP.NET SSO。

async function getUserData() {
    try {
        let userTokenEncoded = await OfficeRuntime.auth.getAccessToken();
        let userToken = jwt_decode(userTokenEncoded); // Using the https://www.npmjs.com/package/jwt-decode library.
        console.log(userToken.name); // user name
        console.log(userToken.preferred_username); // email
        console.log(userToken.oid); // user id     
    }
    catch (exception) {
        if (exception.code === 13003) {
            // SSO is not supported for domain user accounts, only
            // Microsoft 365 Education or work account, or a Microsoft account.
        } else {
            // Handle error
        }
    }
}

何时调用 getAccessToken

如果加载项需要已登录用户，则应从 Office.initialize 内部调用 getAccessToken。还应在 getAccessToken 的 options 参数中传递 allowSignInPrompt: true。例如; OfficeRuntime.auth.getAccessToken( { allowSignInPrompt: true }); 这将确保如果用户尚未登录，Office 会通过 UI 提示用户立即登录。

如果加载项具有一些不需要已登录用户的功能，则可以在用户执行需要已登录用户的操作时调用 getAccessToken 。 getAccessToken 的冗余调用不会导致性能严重降低，因为 Office 会缓存并重用访问令牌，直到其过期，而无需在调用 getAccessToken 时再次调用 Microsoft 标识平台。因此，可以将 getAccessToken 调用添加到所有在需要令牌时启动操作的函数和处理程序。

重要

作为最佳安全做法，请始终在需要访问令牌时调用 getAccessToken。 Office 将为你缓存它。请勿使用自己的代码缓存或存储访问令牌。

将访问令牌传递到服务器端代码

如果需要访问服务器或其他服务 (例如 Microsoft Graph) 上的 Web API，则需要将访问令牌传递到服务器端代码。访问令牌（为经过身份验证的用户）提供对 Web API 的访问权限。如果需要，服务器端代码也可以分析令牌以获取身份信息。（请参阅下面的使用访问令牌作为身份令牌。）有许多可用于不同语言和平台的库可帮助简化你编写的代码。有关详细信息，请参阅 Microsoft 身份验证库 (MSAL) 概述。

如果需要访问 Microsoft Graph 数据，服务器端代码应执行以下操作：

验证访问令牌（请参阅下文“验证访问令牌”）。
通过调用 Microsoft 标识平台来启动 OAuth 2.0 代理流，该平台包括访问令牌、有关用户的一些元数据以及加载项的凭据 (其 ID 和密码)。 Microsoft 标识平台将返回可用于访问 Microsoft Graph 的新访问令牌。
使用新的令牌从 Microsoft Graph 获取数据。
如果需要为多个调用缓存新的访问令牌，我们建议使用 MSAL.NET 中的令牌缓存序列化。

重要

作为最佳安全做法，请始终使用服务器端代码进行 Microsoft Graph 调用或需要传递访问令牌的其他调用。从不将 OBO 令牌返回到客户端，以允许客户端直接调用 Microsoft Graph。这有助于保护令牌免受截获或泄露的侵害。有关正确协议流的详细信息，请参阅 OAuth 2.0 协议图

以下代码显示了将访问令牌传递到服务器端的示例。向服务器端 Web API 发送请求时，令牌在 Authorization 标头中传递。此示例发送 JSON 数据，因此它使用 POST 方法，但 GET 足以在未写入服务器时发送访问令牌。

$.ajax({
    type: "POST",
    url: "/api/DoSomething",
    headers: {
        "Authorization": "Bearer " + accessToken
    },
    data: { /* some JSON payload */ },
    contentType: "application/json; charset=utf-8"
}).done(function (data) {
    // Handle success
}).fail(function (error) {
    // Handle error
}).always(function () {
    // Cleanup
});

如需深入了解如何获得对用户的 Microsoft Graph 数据的授权访问，请参阅向 Office 加载项中的 Microsoft Graph 授权。

验证访问令牌

如果访问令牌从客户端发送，则服务器上的 Web API 必须验证该访问令牌。该令牌是 JSON Web 令牌 (JWT)，这意味着验证方式与大多数标准 OAuth 流中的令牌验证方式类似。有许多可用于处理 JWT 验证的库，而它们的基本内容为：

检查令牌的格式是否正确
检查令牌是否由预期的颁发机构颁发
检查令牌是否是针对 Web API

验证令牌时，请牢记以下准则。

有效的 SSO 令牌是由 Azure 颁发机构 https://login.microsoftonline.com 的。令牌中的 iss 声明应以此值开头。
令牌的 aud 参数将设置为加载项的 Azure 应用注册的应用程序 ID。
令牌的 scp 参数将被设置为 access_as_user。

有关令牌验证的详细信息，请参阅 Microsoft 标识平台访问令牌。

使用访问令牌作为身份令牌

如果加载项需要验证用户身份，则从 getAccessToken() 返回的访问令牌包含可用于创建该身份的信息。令牌中的以下声明与标识相关。

name - 用户的显示名称。
preferred_username - 用户的电子邮件地址。
oid - 表示 Microsoft 标识系统中用户 ID 的 GUID。
tid - 表示用户正在登录的租户的 GUID。

有关这些声明和其他声明的更多详细信息，请参阅 Microsoft 标识平台 ID 令牌。如果需要构建唯一 ID 来表示系统中的用户，请参阅“使用声明可靠地识别用户”以获取详细信息。

示例访问令牌

以下是访问令牌的典型解码有效负载。有关属性的信息，请参阅 Microsoft 标识平台访问令牌。

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

将 SSO 与 Outlook 加载项一起使用

在 Outlook 加载项中使用 SSO 与在 Excel、PowerPoint 或 Word 加载项中使用 SSO 存在一些细微但却重要的差别。请务必阅读使用 Outlook 加载项的单一登录对用户进行身份验证和：在 Outlook 加载项中为服务实现单一登录。

Google Chrome 在 2024 年逐步淘汰第三方 Cookie，并引入了一项名为“跟踪防护”的功能。如果在 Chrome 浏览器中启用了跟踪防护，则加载项将无法使用任何第三方 Cookie。加载项在对用户进行身份验证时可能会遇到问题，例如多个登录请求或错误。

有关改进的身份验证体验，请参阅使用设备状态在浏览器上使用已阻止的第三方 Cookie 改善 SSO 体验。

有关 Google Chrome 推出的详细信息，请参阅以下资源：

在 Office 加载项中启用单一登录 (SSO)

运行时 SSO 的工作方式

要求和最佳做法

不缓存访问令牌

为 Outlook 启用新式身份验证

实施回退身份验证系统

开发 SSO 加载项

向 Microsoft 标识平台注册加载项

配置加载项

包括标识 API 要求集

添加客户端代码

何时调用 getAccessToken

将访问令牌传递到服务器端代码

验证访问令牌

使用访问令牌作为身份令牌

示例访问令牌

将 SSO 与 Outlook 加载项一起使用

另请参阅

反馈

其他资源

在 Office 加载项中启用单一登录 (SSO)

运行时 SSO 的工作方式

要求和最佳做法

不缓存访问令牌

为 Outlook 启用新式身份验证

实施回退身份验证系统

开发 SSO 加载项

向 Microsoft 标识平台注册加载项

配置加载项

包括标识 API 要求集

添加客户端代码

何时调用 getAccessToken

将访问令牌传递到服务器端代码

验证访问令牌

使用访问令牌作为身份令牌

示例访问令牌

将 SSO 与 Outlook 加载项一起使用

Google Chrome 第三方 Cookie 支持

另请参阅

反馈

其他资源