嵌套应用身份验证和 Outlook 旧版令牌弃用常见问题解答

旧版Exchange Online用户标识令牌和回调令牌已弃用，并在所有Microsoft 365 个租户中关闭。 如果 Outlook 外接程序需要委派的用户访问或用户标识，我们建议使用 MSAL (Microsoft 身份验证库) 和嵌套应用身份验证。

常规常见问题解答

什么是 NAA) (嵌套应用身份验证？

嵌套应用身份验证为嵌套在受支持的 Microsoft 应用程序（如 Outlook）中的应用程序启用单一登录 (SSO) 。 与现有的完全信任身份验证模型和代理流相比，NAA 在应用体系结构中提供了更好的安全性和更大的灵活性，从而支持创建丰富的客户端驱动应用程序。 有关详细信息，请参阅 使用嵌套应用身份验证在 Office 外接程序中启用 SSO。

关闭旧版 Exchange 联机令牌时间线是什么？

旧Exchange Online令牌已关闭。 如果你是租户的管理员，并且已获得针对租户的Microsoft豁免，则本常见问题解答中的大部分仍然适用于你。 所有豁免均于 2025 年 10 月 31 日结束。 不再允许豁免。

NAA 何时对我的频道正式发布？

NAA 的正式发布 (正式发布) 日期取决于你正在使用的频道。 下表列出了 Outlook 的内部版本和正式版信息。

COM 加载项是否受到弃用旧Exchange Online令牌的影响？

弃用旧Exchange Online令牌不太可能影响任何 COM 加载项。 Outlook Web 加载项主要受到影响，因为它们可以使用依赖于 Exchange 令牌 Office.js API。 有关详细信息，请参阅如何实现知道我的 Outlook 外接程序是否依赖于旧令牌？。 Exchange 令牌用于访问 Exchange Web Services (EWS) 或 Outlook REST API，这两者也已弃用。

Microsoft 365 个管理员问题

我的组织中的哪些加载项受到影响？

Get-AuthenticationPolicy使用 命令获取租户上使用旧版Exchange Online令牌的所有 Outlook 加载项的列表。 有关详细信息，请参阅打开或关闭旧Exchange Online令牌。 获得加载项列表后，需要联系发布者，了解有关其更新计划的详细信息。 在某些情况下，加载项可能由你自己的组织开发。 你需要联系组织中的相应开发团队。

可以使用哪些命令来标识发布者？

有一些Exchange Online PowerShell 命令可用于跟踪有关 Outlook 加载项的其他信息。

若要查找用户计算机上安装的加载项列表，用户可以运行以下命令。

Get-App | Select-Object -Property ProviderName, DisplayName, AppId

以下屏幕截图显示了运行 命令的示例 Get-App 。

ProviderName 将帮助你确定加载项的发布者，以便你可以与他们联系。 AppId 可用于获取有关加载项的其他详细信息。

若要通过 AppId 以下命令查找有关加载项的信息。

Get-App -Identity {identity} | Select-Object -Property ProviderName, DisplayName

以下屏幕截图显示了使用 必应地图 ID 获取详细信息的示例。

还可以在加载项的清单文件中找到其他信息。 清单包含 URL 终结点，这些终结点还可以帮助你标识和联系发布者。 使用以下命令获取清单。

Get-App -Identity {identity} | Select-Object -Property ManifestXml

以下屏幕截图显示了使用 ID 获取必应地图的 XML 清单的示例。

ISV 如何知道其加载项正在使用旧令牌？

加载项可以使用旧令牌通过 EWS 或 Outlook REST API 从 Exchange 获取资源。 有时，加载项需要 Exchange 资源用于某些用例，而不是其他用例，因此很难确定加载项是否需要更新。 我们建议联系加载项开发人员和所有者，询问他们的外接程序代码是否引用了以下 API。

• makeEwsRequestAsync
• getUserIdentityTokenAsync
• getCallbackTokenAsync

如果你的加载项依赖于 ISV，我们建议你尽快与他们联系，以确认他们有转移旧 Exchange 令牌的计划和时间线。 ISV 开发人员应直接与其Microsoft联系人联系，询问问题，以确保他们已准备好结束 Exchange 旧版令牌。 如果你依赖于组织中的开发人员，他们应查看此常见问题解答和文章 使用嵌套应用身份验证在 Office 外接程序中启用 SSO。 应在 OfficeDev/office-js GitHub 问题网站上提出任何问题。

对于无法识别的加载项，我该怎么办？

如果在运行 Get-AuthenticationPolicy后遇到无法识别的加载项，请尝试执行尖叫测试以确定所有权。

在执行尖叫测试之前，你可能希望提前（例如通过电子邮件）告知用户，将进行一个测试来关闭旧版令牌，并且可能会影响某些 Outlook 加载项。应考虑为用户提供以下信息。

• 测试的预期时间段。
• 如果有已知的 Outlook 加载项会中断，例如从已识别的Microsoft市场部署的加载项。
• 一般情况下，Outlook 加载项不应中断。 但是，如果他们确实看到问题，请要求用户报告加载项的名称、说明以及观察到的任何错误信息。

使用以下步骤执行测试。

1. 运行以下命令，关闭租户上的旧Exchange Online令牌。 有关如何使用此命令的详细信息，请参阅打开或关闭旧版Exchange Online令牌。

   Set-AuthenticationPolicy -BlockLegacyExchangeTokens -Identity "LegacyExchangeTokens"

2. 等待适当的时间，以便用户报告加载项的任何问题。命令关闭所有用户的旧Exchange Online令牌大约需要 24 小时。 用户可能需要一两天时间才能报告 Outlook 加载项的任何问题。

3. 识别任何受影响的 Outlook 加载项。如果用户提交标识中断性问题的问题，请务必获取受影响的 Outlook 加载项的名称和说明。 此外，捕获错误或行为，以便此信息可以一起传递给发布者。

4. 如果中断了任何业务关键型加载项，请使用以下命令重新打开令牌。 有关如何使用此命令的详细信息，请参阅打开或关闭旧版Exchange Online令牌。

   Set-AuthenticationPolicy -AllowLegacyExchangeTokens -Identity "LegacyExchangeTokens"

   令牌大约需要 24 小时才能为租户上的所有用户重新打开。

5. 如果没有中断性问题的报告，我们建议将旧Exchange Online令牌保留为安全最佳做法。

是否可以重新打开Exchange Online旧版令牌？

只有在获得Microsoft豁免后，才能打开旧令牌。 有关如何打开或关闭旧版令牌的详细信息，请参阅打开或关闭旧Exchange Online令牌。 所有豁免均于 2025 年 10 月 31 日结束。 不再允许豁免。

管理员同意流的工作原理是什么？

独立软件供应商 (ISV) 正在更新其加载项，以使用Entra ID令牌和Microsoft Graph 范围。 当加载项请求访问令牌时，它必须获得管理员或用户同意。 如果管理员同意，租户上的所有用户都可以将加载项用于外接程序所需的范围。 否则，如果启用了用户同意，则会提示每个最终用户 同意。 为了获得更好的体验，因为用户未收到提示，请完成管理员同意。

一种许可选项是 ISV 提供管理员同意 URI。

1. 外接程序开发人员提供管理员同意 URI。 如果这不在他们提供的文档中，则需要与他们联系以获取详细信息。
2. 管理员浏览到管理员同意 URI。
3. 系统会提示管理员登录并同意加载项所需的范围列表。
4. 完成后，浏览器将从 ISV 重定向到网页，这应显示同意已成功。

作为替代方法，ISV 可以提供更新的应用清单，该清单将提示管理员同意作为中央部署的一部分。 在此方案中，部署更新的应用清单时，系统会提示你同意，然后才能完成部署。 无需管理员同意 URI。

最后，如果加载项在 Microsoft 365 存储中发布，则会自动部署更新，并且系统会提示管理员同意范围。 如果管理员不同意，用户将无法使用更新的加载项。

如果加载项在管理员同意后无法正常工作，该怎么办？

确保不禁用功能或撤销加载项所需的权限。 有关示例，请参阅 修改邮箱策略属性。 加载项使用委托的权限，因此有权访问与登录用户相同的资源。 但是，如果策略或设置阻止用户访问特定资源或作，则也会阻止加载项。

如何实现从 ISV 部署加载项更新？

如果你有使用旧版 Exchange 令牌的外接程序，则应联系 ISV，了解有关其迁移加载项以使用 NAA 时间线的信息。 ISV 迁移其加载项后，他们很可能提供管理员同意 URL。 有关详细信息，请参阅 管理员同意流如何工作？ 。

ISV 还可以为你提供更新的应用清单，以便通过集中部署进行部署。 在集中部署期间，这可能会提示你同意加载项要求的任何Microsoft Graph 范围。 在此方案中，无需使用管理员同意 URI。

如果加载项是从 Microsoft 市场部署的，则当 ISV 向外接程序推出更新时，很可能系统会提示你同意Microsoft Graph 范围。 除非你同意，否则租户上的用户将无法将新版本的外接程序与 NAA 一起使用。

在哪里可以找到哪些加载项已获得同意？

管理员或用户同意后，它将在Microsoft Entra管理中心列出。 可以使用以下步骤查找应用注册。

1. 转到 https://entra.microsoft.com/#home ，并在租户上以管理员身份登录。
2. 在左侧导航窗格中，选择“ 应用程序>企业应用程序”。
3. 在 “企业应用程序 ”页上的“ 管理 ”部分，选择“ 所有应用程序”。
4. 选择加载项。 这将打开概述页。 在概述页中，选择“ 权限”。 有两个权限视图：管理员同意和用户同意。 选择“用户同意”，查看任何单独的同意。

是否有更新了加载项的发布者列表？

一些广泛使用的 Outlook 外接程序发布者已更新其加载项，如下所示。

• 适用于 Outlook 的应用优先级矩阵
• Atlassian Jira Cloud for Outlook
• 适用于 Outlook 的 Box
• Outlook 点击更新
• iEnterprises® - Outlook 连接器
• HubStar Connect
• SalesForce for Outlook
• LawToolBox
• OnePlace 解决方案
• Set-OutlookSignatures Benefactor Circle
• Wrike
• Zoho CRM for Email
• Zoho Recruit for Email
• Zoho Projects for Email
• Zoho Sign for Outlook
• Zoho WorkDrive for Email
• 发票和时间跟踪 - Zoho 发票

如果发布者更新了其清单，并且加载项是通过Microsoft存储部署的，系统会提示你以管理员身份升级和部署更新。 如果发布者更新了其清单，并且加载项是通过集中部署部署的，则需要以管理员身份部署新清单。 在某些情况下，发布者可能有管理员同意 URI，你需要使用 来同意加载项的新范围。 如果需要有关更新加载项的详细信息，请联系发布者。

Outlook 加载项迁移常见问题解答

为什么Microsoft使 Outlook 加载项迁移？

使用 Entra ID 令牌切换到 Microsoft Graph 对 Outlook 和 Exchange 客户的安全性有了很大的改进。 Entra ID (以前是 Azure Active Directory) ，是基于云的领先标识和访问管理服务。 客户可以利用零信任功能，例如条件访问、MFA 要求、持续令牌监视、实时安全启发法，以及旧版 Exchange 令牌无法提供的更多功能。 客户将重要的业务数据存储在 Exchange 中，因此我们必须确保此数据受到保护。 迁移整个 Outlook 生态系统以将Entra ID令牌与 Microsoft Graph 配合使用可极大地提高客户数据的安全性。

我的 Outlook 加载项是否必须迁移到 NAA？

不正确。 尽管 NAA 为用户提供了最佳的身份验证体验和组织的最佳安全状况，但 Outlook 加载项不必使用 NAA。 如果加载项未使用旧版 Exchange 令牌，则它们不会受到弃用 Exchange 令牌的影响。 使用 MSAL.js 或其他依赖于Entra ID的 SSO 方法的加载项将继续工作。

如何实现知道我的 Outlook 外接程序是否依赖于旧版令牌？

若要了解外接程序是否使用旧版 Exchange 用户标识令牌和回调令牌，请在代码中搜索对以下 API 的调用。

• makeEwsRequestAsync
• getUserIdentityTokenAsync
• getCallbackTokenAsync

如果外接程序调用这些 API 中的任何一个，则应采用 NAA 并迁移到使用 Entra ID 令牌来访问 Microsoft Graph。

哪些 Outlook 加载项在范围内？

许多主要加载项都在范围内。 如果外接程序使用 EWS 或 Outlook REST 访问Exchange Online资源，则几乎可以肯定需要从旧版 Outlook 令牌迁移到 NAA。 如果你的外接程序只用于 Exchange 本地 (例如 Exchange 2019) ，则不受此更改的影响。

如果我不迁移到 NAA，我的 Outlook 加载项会发生什么情况？

如果不将 Outlook 加载项迁移到 NAA，它们将在 Exchange Online 中停止按预期工作。 关闭 Exchange 令牌后，Exchange Online将阻止旧令牌颁发。 任何使用旧令牌的外接程序都无法访问 Exchange 联机资源。 当外接程序调用请求 Exchange 令牌的 API 时 getUserIdentityTokenAsync，它会收到类似于以下内容的一般错误，错误代码为 9017 或 9018。

• “GenericTokenError：发生了内部错误。”
• “InternalServerError：Exchange 服务器返回错误。 有关详细信息，请查看 诊断 对象。”

如果外接程序仅在本地工作，或者外接程序位于弃用路径上，则可能不需要更新。 但是，通过 EWS 或 Outlook REST 访问 Exchange 资源的大多数加载项必须迁移才能继续按预期运行。

如何实现将 Outlook 加载项迁移到 NAA？

若要在 Outlook 加载项中支持 NAA，请参阅以下文档和示例。

• 使用嵌套应用身份验证在 Office 外接程序中启用 SSO。
• 使用嵌套应用身份验证进行 SSO 的 Outlook 外接程序。

如何实现跟上最新指南？

我们将更新此常见问题解答，因为有新信息可用。 我们将在 Office 加载项社区通话 和 M365 开发人员博客上分享更多指导。 最后，可以在 OfficeDev/office-js GitHub 问题网站上提出有关 NAA 和旧版Exchange Online令牌弃用的问题。 请在标题中放入“NAA”，以便我们可以对问题进行分组和确定优先级。

如果提交问题，请提供以下信息。

• Outlook 客户端版本。
• 适用于客户端) 的 Outlook 发布频道受众 (。
• 问题的屏幕截图。
• (Windows、Outlook (新) 、Mac、iOS、Android) 出现问题的平台。
• 遇到问题的会话 ID。
• 正在使用的帐户类型。
• msal-browser 的版本。
• msal-browser 中的日志。

开发人员问题

如何实现从 MSAL 和 NAA 获取更多调试信息？

初始化可嵌套的公共客户端应用程序时，使用以下代码在 msalConfig 中启用调试信息。 这会将其他详细信息记录到控制台。

const msalConfig = {
  auth: {...},
  system: {
    loggerOptions: {
      logLevel: LogLevel.Verbose,
      loggerCallback: (level, message, containsPii) => {
        switch (level) {
          case LogLevel.Error:
            console.error(message);
            return;
          case LogLevel.Info:
            console.info(message);
            return;
          case LogLevel.Verbose:
            console.debug(message);
            return;
          case LogLevel.Warning:
            console.warn(message);
            return;
        }
      },
    }
  }
};

测试更新的加载项

将加载项更新为使用 NAA 后，应在支持的所有平台上对其进行测试，例如 Mac、移动、Web 和 Windows 版 Outlook。

测试 Exchange 令牌何时关闭

若要测试加载项在关闭 Exchange 令牌时是否正常工作，请将加载项部署到已关闭令牌的租户并对其进行测试。 若要关闭令牌，请参阅打开或关闭旧版Exchange Online令牌。

如果已实现一种模式，即代码使用 Exchange 令牌，但在这些令牌不可用时会中断，请确保检查正确的错误。 当获取 Exchange 令牌的调用失败时，检查 asyncResult.诊断。 如果返回以下任一错误，请切换到 NAA。

• GenericTokenError: An internal error has occurred.
• InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.

测试 Trident+ Webview 的回退代码

如果 Outlook 加载项支持 Windows 上的 Outlook 2016 或 Outlook 2019，请在使用 Trident+ (Internet Explorer 11) Webview 时测试它是否正常工作。 使用 Trident+ Webview 时，代码必须回退到 MSAL v2 才能打开对话框并登录用户。 有关如何实现回退模式的详细信息，请参阅 使用嵌套应用身份验证（包括 Internet Explorer 回退）使用 SSO 的 Outlook 外接程序。

在 Trident+ 和 WebView2 中测试

Outlook 2016和 Windows 上的 Outlook 2019 基于各种作系统条件使用 Trident+ 或 WebView2。

• 有关何时使用 Trident+ 或 Webview2 的详细信息，请参阅 Office 外接程序使用的浏览器和 Webview 控件。
• 有关如何确定哪个 Web 视图正在运行的详细信息，请参阅 支持较旧的Microsoft Web 视图和 Office 版本

MSAL 返回哪些令牌，是否有最小范围可以请求？

通过 MSAL 请求令牌时，它始终返回三个令牌。

MSAL 始终返回这三个令牌。 它请求 profile、 openid和 offline_access 作为默认范围，即使令牌请求不包括它们。 这可确保请求 ID 和刷新令牌。 但是，必须至少包含一个资源范围，例如 user.read ，以便获取访问令牌。 否则，请求可能会失败。

是否应从 MSAL 验证 ID 令牌？

不正确。 这是与 Exchange 令牌一起使用的旧式身份验证模式，用于授权访问你自己的资源。 通过网络调用传递 ID 令牌以启用或授权访问服务是一种安全反模式。 ID 令牌仅适用于客户端 (任务窗格) ，服务无法可靠地使用该令牌来确保用户具有授权的访问权限。 有关 ID 令牌声明的详细信息，请参阅 ID 令牌声明参考。

请务必始终向自己的服务请求访问令牌。 访问令牌还包括相同的 ID 声明，因此无需传递 ID 令牌。 请改为为服务创建自定义范围。 有关你自己的服务的应用注册设置的详细信息，请参阅 受保护的 Web API：应用注册。 当服务收到访问令牌时，它可以对其进行验证，并使用访问令牌内部的 ID 声明。

为什么我收到来自条件访问策略的错误？

已批准的客户端应用条件访问授权已弃用，将于 2026 年 3 月停用。 MSAL NAA 不支持此策略，即使向加载项授予此策略的例外，也会返回错误 (。) 若要从此策略中迁移，请参阅 在条件访问中将批准的客户端应用程序迁移到应用程序保护策略。

某些条件访问策略会导致使用 MSAL NAA 的加载项出现问题，具体取决于它们对客户端的需求。 这些策略通常与设备管理策略相关。 有关详细信息，请参阅 如何创建和分配应用保护策略中的设备管理类型。

有时需要根据策略处理声明质询。 若要详细了解如何处理外接程序中的声明质询，请参阅 声明质询、声明请求和客户端功能。

为什么不刷新 ID 令牌？

存在一个已知问题，即 MSAL 有时会在 ID 令牌过期后不刷新该令牌。 这不会在加载项中引起任何问题，因为 ID 令牌仅用于在任务窗格中获取基本的用户标识信息，例如名称和电子邮件。 没有理由验证 ID 令牌或检查过期声明。 如果需要对自己的资源对用户进行身份验证，请使用访问令牌，该令牌还包含用户标识信息。 ID 令牌绝不能在接收它的客户端代码之外传递。

如何实现确定用户是联机帐户还是本地帐户？

可以使用 Office.UserProfile.accountType 属性确定登录用户是否具有Exchange Online帐户或本地 Exchange 帐户。 如果帐户类型属性值为 enterprise，则邮箱位于本地 Exchange 服务器上。 请注意，批量许可的永久Outlook 2016不支持 accountType 属性。 若要解决此问题，请在 Exchange 本地服务器中调用 Exchange Web Service (EWS) 中的 ResolveNames 作以获取收件人类型。

accountType 属性需要邮箱要求集 1.6。 在较旧的 Outlook 客户端上，你需要使用自动发现服务，如下所示。

调用 outlook.office365.com 域的自动发现终结点。 https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/{email}?Protocol=EWS&ServerLocation=true

• 对于联机帐户，该服务将返回一个结果，其中ServerLocation密钥设置为 Exchange Online。
• 对于 本地 帐户，该服务不会返回 ServerLocation 密钥。

如何实现将外接程序部署到 Microsoft 市场

如果要将新加载项发布到 Microsoft 市场，则需要完成认证过程。 有关详细信息，请参阅 将 Office 外接程序发布到 Microsoft 市场。 如果要更新已发布到 Microsoft 市场的加载项清单，则需要再次完成认证过程。 你可以随时在 Web 服务器上更新加载项的源代码，而无需完成认证过程。

如果你的外接程序通过 NAA 使用 SSO，则外接程序必须符合以下发布准则。

• 1000.3 身份验证选项
• 1120.3 功能

请务必正确处理管理员同意。 请参阅 发布需要管理员同意的外接程序Microsoft Graph 范围

有关其他部署详细信息，请参阅 在 Microsoft 市场中和 Office 中提供解决方案。 如果更新加载项 (更改清单) 需要 再次完成认证过程。 你可以随时更新 Web 服务器代码，而无需查看。

用户在登录时收到无法解释的错误

当加载项请求令牌时，用户可能会看到一个登录弹出对话框，其中显示以下错误之一。

• 发生了错误。 [错误代码]
• 无法从此处到达

检查管理员是否应用了任何强制实施特定客户端限制的条件访问策略，例如移动位置或平台类型。 此外， 已批准的客户端应用条件访问授权 已弃用，并且会导致 NAA 令牌请求出现这些错误。 管理员必须完全删除此策略并切换到较新的 应用程序保护策略授权 ，NAA 才能正常工作。 有关详细信息，请参阅 在条件访问中将批准的客户端应用迁移到应用程序保护策略。

相关内容

• 使用嵌套应用身份验证在 Office 外接程序中启用 SSO。
• 使用嵌套应用身份验证进行 SSO 的 Outlook 外接程序。