排查单一登录 (SSO) 错误消息Troubleshoot error messages for single sign-on (SSO)

本文提供了一些指南,介绍了如何排查 Office 加载项中出现的单一登录 (SSO) 问题,以及如何让已启用 SSO 的加载项可靠地处理特殊条件或错误。This article provides some guidance about how to troubleshoot problems with single sign-on (SSO) in Office Add-ins, and how to make your SSO-enabled add-in robustly handle special conditions or errors.

备注

目前,Word、Excel、Outlook 和 PowerPoint 支持单一登录 API。The Single Sign-on API is currently supported for Word, Excel, Outlook, and PowerPoint. 若要详细了解目前支持单一登录 API 的平台,请参阅 IdentityAPI 要求集For more information about where the Single Sign-on API is currently supported, see IdentityAPI requirement sets. 如果使用的是 Outlook 加载项,请务必为 Microsoft 365 租赁启用新式验证。If you are working with an Outlook add-in, be sure to enable Modern Authentication for the Microsoft 365 tenancy. 若要了解如何这样做,请参阅 Exchange Online:如何为租户启用新式验证For information about how to do this, see Exchange Online: How to enable your tenant for modern authentication.

调试工具Debugging tools

开发时,强烈建议使用具有以下功能的工具:能够截获并显示加载项 Web 服务发出的 HTTP 请求和发送给它的响应。最热门的两个工具是:We strongly recommend that you use a tool that can intercept and display the HTTP Requests from, and Responses to, your add-in's web service when you are developing. Two of the most popular are:

导致 getAccessToken 生成错误的原因和处理方法Causes and handling of errors from getAccessToken

有关此部分中介绍的错误处理示例,请参阅:For examples of the error handling described in this section, see:

1300013000

加载项或 Office 版本不支持 getAccessToken API。The getAccessToken API is not supported by the add-in or the Office version.

  • Office 版本不支持 SSO。The version of Office does not support SSO. 所需版本是 Microsoft 365 订阅,位于任何每月频道中。The required version is Microsoft 365 subscription, in any monthly channel.
  • 加载项清单缺少适当的 WebApplicationInfo 部分。The add-in manifest is missing the proper WebApplicationInfo section.

加载项应该通过回退到用户身份验证备用系统来响应此错误。Your add-in should respond to this error by falling back to an alternate system of user authentication. 有关详细信息,请参阅要求和最佳做法For more information, see Requirements and Best Practices.

1300113001

用户未登录 Office。The user is not signed into Office. 在大多数情况下,应通过在 AuthOptions 参数中传递选项 allowSignInPrompt: true 来防止出现此错误。In most scenarios, you should prevent this error from ever being seen by passing the option allowSignInPrompt: true in the AuthOptions parameter.

但是,可能会出现异常情况。But there may be exceptions. 例如,你希望加载项打开要求用户登录的功能;但 前提 是该用户 已经 登录 Office。For example, you want the add-in to open with features that require a logged in user; but only if the user is already logged into Office. 如果用户未登录,则你希望该加载项打开不要求用户登录的备用功能集。If the user is not, you want the add-in to open with an alternate set of features that do not require that the user is signed in. 在这种情况下,当加载项启动时运行的逻辑将调用不具有 allowSignInPrompt: truegetAccessTokenIn this case, logic which runs when the add-in launches calls getAccessToken without allowSignInPrompt: true. 使用 13001 错误作为标志,告诉加载项显示备用功能集。Use the 13001 error as the flag to tell the add-in to present the alternate set of features.

另一个选项是通过回退到用户身份验证备用系统来响应 13001。Another option is to respond to 13001 by falling back to an alternate system of user authentication. 这会使用户登录到 AAD,但不会使用户登录到 Office。This will sign the user into AAD, but not sign the user into Office.

Office 网页版 中绝不会出现此错误。This error is never seen in Office on the web. 如果用户的 Cookie 到期,Office 网页版 将返回错误 13006。If the user's cookie expires, Office on the web returns error 13006.

1300213002

用户中止登录或同意(例如,在同意对话框中选择 取消)。The user aborted sign in or consent; for example, by choosing Cancel on the consent dialog.

  • 如果加载项提供的功能无需用户登录(或授予许可),代码应捕获此错误,并让加载项继续正常运行。If your add-in provides functions that don't require the user to be signed in (or to have granted consent), then your code should catch this error and allow the add-in to stay running.
  • 如果加载项需要登录用户授予许可,则代码应显示一个登录按钮。If the add-in requires a signed-in user who has granted consent, your code should have a sign-in button appear.

1300313003

用户类型不受支持。User Type not supported. 用户未使用有效的 Microsoft 帐户或 Microsoft 365 教育版或工作帐户登录 Office。The user isn't signed into Office with a valid Microsoft account or Microsoft 365 Education or work account. 例如,当使用本地域帐户运行 Office 时,可能会生成此错误。This may happen if Office runs with an on-premises domain account, for example. 代码应回退到用户身份验证备用系统。Your code should fall back to an alternate system of user authentication. 在 Outlook 中,如果在 Exchange Online 中为用户的租户禁用新式验证,也可能会发生此错误。In Outlook, this error may also occur if modern authentication is disabled for the user's tenant in Exchange Online. 有关详细信息,请参阅要求和最佳做法For more information, see Requirements and Best Practices.

1300413004

资源无效。Invalid Resource. (此错误应仅在开发中出现。) 加载项清单尚未正确配置。(This error should only be seen in development.) The add-in manifest hasn't been configured correctly. 请更新此清单。Update the manifest. 有关详细信息,请参阅验证 Office 加载项的清单For more information, see Validate an Office Add-in's manifest. 最常见的问题是 资源 元素(在 WebApplicationInfo 元素中)具有与加载项的域不匹配的域。The most common problem is that the Resource element (in the WebApplicationInfo element) has a domain that does not match the domain of the add-in. 虽然资源值的协议部分应该是“api”而不是“https”;域名的所有其他部分(包括端口,如果有)应与加载项域名的相应部分相同。Although the protocol part of the Resource value should be "api" not "https"; all other parts of the domain name (including port, if any) should be the same as for the add-in.

1300513005

授权无效。Invalid Grant. 这通常意味着,Office 尚未获得对加载项 Web 服务的预授权。This usually means that Office has not been pre-authorized to the add-in's web service. 有关详细信息,请参阅创建服务应用程序向 Azure AD v2.0 终结点注册加载项For more information, see Create the service application and Register the add-in with Azure AD v2.0 endpoint. 如果用户未授权服务应用程序访问其 profile,或已吊销许可,也可能会生成此错误。This also may happen if the user has not granted your service application permissions to their profile, or has revoked consent. 代码应回退到用户身份验证备用系统。Your code should fall back to an alternate system of user authentication.

另一个可能的原因是,在开发过程中,加载项使用的是 Internet Explorer,并且你使用的是自签名证书。Another possible cause, during development, is that your add-in using Internet Explorer, and you are using a self-signed certificate. (若要确定加载项使用的浏览器,请参阅 Office 加载项使用的浏览器。)(To determine which browser is being used by the add-in, see Browsers used by Office Add-ins.)

1300613006

客户端错误。Client Error. 此错误仅出现在 Office 网页版 中。This error is only seen in Office on the web. 代码应提示用户注销,然后重启 Office 浏览器会话。Your code should suggest that the user sign out and then restart the Office browser session.

1300713007

Office 应用程序无法获取对加载项 Web 服务的访问令牌。The Office application was unable to get an access token to the add-in's web service.

  • 如果在开发过程中发生此错误,请确保加载项注册和加载项清单指定 profile 权限(和 openid 权限 - 如果你使用的是 MSAL.NET)。If this error occurs during development, be sure that your add-in registration and add-in manifest specify the profile permission (and the openid permission, if you are using MSAL.NET). 如需了解更多信息,请参阅向 Azure AD v2.0 终结点注册加载项For more information, see Register the add-in with Azure AD v2.0 endpoint.

  • 在生产中,有几种情况可能导致此错误。In production, there are several things that can cause this error. 其中一些是:Some of them are:

    • 用户具有 Microsoft 帐户标识。The user has a Microsoft account identity.
    • 使用 MSA 时,导致 Microsoft 365 教育版或工作帐户出现其他 13xxx 错误之一的一些情况将导致 13007。Some situations that would cause one of the other 13xxx errors with a Microsoft 365 Education or work account will cause a 13007 when a MSA is used.

    对于所有这些情况,代码应回退到用户身份验证备用系统。For all of these cases, your code should fall back to an alternate system of user authentication.

1300813008

用户在上一次调用 getAccessToken 完成前触发了调用 getAccessToken 的操作。The user triggered an operation that calls getAccessToken before a previous call of getAccessToken completed. 此错误仅出现在 Office 网页版 中。This error is only seen on Office on the web. 代码应提示用户在上一次操作完成后再重复此操作。Your code should ask the user to repeat the operation after the previous operation has completed.

1301013010

用户正在 Microsoft Edge 或 Internet Explorer 上的 Office 中运行加载项。The user is running the add-in in Office on Microsoft Edge or Internet Explorer. 用户的 Microsoft 365 域和域在浏览器设置 login.microsoftonline.com 中的不同安全区域中。The user's Microsoft 365 domain, and the login.microsoftonline.com domain, are in a different security zones in the browser settings. 此错误仅出现在 Office 网页版 中。This error is only seen on Office on the web. 如果此错误返回,用户将已看到对此进行解释的错误,并链接到关于如何更改区域配置的页面。If this error is returned, the user will have already seen an error explaining this and linking to a page about how to change the zone configuration. 如果加载项提供的功能无需用户登录,代码应捕获此错误,并让加载项继续正常运行。If your add-in provides functions that don't require the user to be signed in, then your code should catch this error and allow the add-in to stay running.

1301213012

存在几种可能的原因:There are several possible causes:

  • 加载项在不支持 getAccessToken API的平台上运行。The add-in is running on a platform that does not support the getAccessToken API. 例如,在 iPad 上它不受支持。For example, it is not supported on iPad. 另请参阅标识 API 要求集See also Identity API Requirement Sets.
  • forMSGraphAccess 选项在调用中传递给 getAccessToken,并且用户从 AppSource 获得了加载项。The forMSGraphAccess option was passed in the call to getAccessToken and the user obtained the add-in from AppSource. 在此方案中,对于所需的 Microsoft Graph 范围(权限),租户管理员未向加载项授予许可。In this scenario, the tenant admin has not granted consent to the add-in for the Microsoft Graph scopes (permissions) that it needs. 撤回具有 allowConsentPromptgetAccessToken 将无法解决此问题,因为允许 Office 提示用户仅同意 AAD profile 范围。Recalling getAccessToken with the allowConsentPrompt will not solve the problem because Office is allowed to prompt the user for consent to only the AAD profile scope.

代码应回退到用户身份验证备用系统。Your code should fall back to an alternate system of user authentication.

在开发中,该加载项在 Outlook 中旁加载,并且在 getAccessToken 调用中传递了 forMSGraphAccess 选项。In development, the add-in is sideloaded in Outlook and the forMSGraphAccess option was passed in the call to getAccessToken.

1301313013

调用时间过短,因此 Office 限制最近 getAccessToken 一次调用。The getAccessToken was called too many times in a short amount of time, so Office throttled the most recent call. 这通常是由对方法的无限循环调用导致的。This is usually caused by an infinite loop of calls to the method. 建议在一些方案中撤回此方法。There are scenarios when recalling the method is advisable. 但是,您的代码应该使用计数器或标志变量来确保不会重复调用该方法。However, your code should use a counter or flag variable to ensure that the method is not recalled repeatedly. 如果再次运行相同的"重试"代码路径,则代码应回退到用户身份验证的备用系统。If the same "retry" code path is running again, the code should fall back to an alternate system of user authentication. 有关代码示例,请参阅变量在HomeES6.jsretryGetAccessTokenssoAuthES6.js中ssoAuthES6.js。 For a code example, see how the retryGetAccessToken variable is used in HomeES6.js or ssoAuthES6.js.

5000150001

此错误(未特定于 getAccessToken)可能表示浏览器已缓存 office.js 文件的旧副本。This error (which is not specific to getAccessToken) may indicate that the browser has cached an old copy of the office.js files. 在开发时,清除浏览器的缓存。When you are developing, clear the browser's cache. 另一种可能是 Office 的版本不够新,不足以支持 SSO。Another possibility is that the version of Office is not recent enough to support SSO. 在 Windows 上,最低版本是 16.0.12215.20006。On Windows, the minimum version is 16.0.12215.20006. 在 Mac 上,它是 16.32.19102902。On Mac, it is 16.32.19102902.

在生产加载项中,加载项应该通过回退到用户身份验证备用系统来响应此错误。In a production add-in, the add-in should respond to this error by falling back to an alternate system of user authentication. 有关详细信息,请参阅要求和最佳做法For more information, see Requirements and Best Practices.

Azure Active Directory 服务器端错误Errors on the server-side from Azure Active Directory

有关此部分中介绍的错误处理示例,请参阅:For samples of the error-handling described in this section, see:

条件访问/多重身份验证错误Conditional access / Multifactor authentication errors

在 AAD 和 Microsoft 365 中的某些标识配置中,某些可通过 Microsoft Graph 访问的资源可能需要多重身份验证 (MFA) ,即使用户的 Microsoft 365 租赁不要求这样做。In certain configurations of identity in AAD and Microsoft 365, it is possible for some resources that are accessible with Microsoft Graph to require multifactor authentication (MFA), even when the user's Microsoft 365 tenancy does not. 通过代表流收到对 MFA 保护资源的令牌请求时,AAD 会向加载项 Web 服务返回包含 claims 属性的 JSON 消息。When AAD receives a request for a token to the MFA-protected resource, via the on-behalf-of flow, it returns to your add-in's web service a JSON message that contains a claims property. claims 属性指明需要进一步执行哪几重身份验证。The claims property has information about what further authentication factors are needed.

代码应对此 claims 属性进行测试。Your code should test for this claims property. 根据加载项的体系结构,你可以在客户端进行测试,也可以在服务器端进行测试并将其中继到客户端。Depending on your add-in's architecture, you may test for it on the client-side, or you may test for it on the server-side and relay it to the client. 客户端需要此信息,因为 Office 处理 SSO 加载项的身份验证。如果从服务器端进行中继,则发送到客户端的消息可以是错误(如 500 Server Error401 Unauthorized),也可以是成功响应的正文部分(如 200 OK)。You need this information in the client because Office handles authentication for SSO add-ins. If you relay it from the server-side, the message to the client can be either an error (such as 500 Server Error or 401 Unauthorized) or in the body of a success response (such as 200 OK). 无论属于上述哪种情况,代码对加载项 Web API 的客户端 AJAX 调用的(失败或成功)回调都应测试此响应是否有错。In either case, the (failure or success) callback of your code's client-side AJAX call to your add-in's web API should test for this response.

无论体系结构如何,如果声明值已从 AAD 发送,则代码应调用并传递 getAccessToken 参数 authChallenge: CLAIMS-STRING-HERE options 中的选项。Regardless of your architecture, if the claims value has been sent from AAD, your code should recall getAccessToken and pass the option authChallenge: CLAIMS-STRING-HERE in the options parameter. 如果 AAD 看到此字符串,它会先提示用户进行多重身份验证,再返回将在代表流中接受的新访问令牌。When AAD sees this string, it prompts the user for the additional factor(s) and then returns a new access token which will be accepted in the on-behalf-of flow.

如果 AAD 未记录用户(或租户管理员)已授权加载项访问 Microsoft Graph 资源,AAD 会向 Web 服务发送错误消息。If AAD has no record that consent (to the Microsoft Graph resource) was granted to the add-in by the user (or tenant administrator), AAD will send an error message to your web service. 代码必须指示客户端(例如,在 403 Forbidden 响应的正文中)。Your code must tell the client (in the body of a 403 Forbidden response, for example).

如果加载项需要只能由管理员许可的 Microsoft Graph 范围,则代码应该会引发错误。If the add-in needs Microsoft Graph scopes that can only be consented to by an admin, your code should throw an error. 如果用户只能许可所需的范围,则代码应回退到用户身份验证备用系统。If the only scopes that are needed can be consented to by the user, then your code should fall back to an alternate system of user authentication.

范围(权限)无效或缺失错误Invalid or missing scope (permission) errors

应该只会在开发中看到此类错误。This kind of error should only be seen in development.

  • 服务器端代码应向客户端发送 403 Forbidden 响应,它应该会在控制台或日志中记录此错误。Your server-side code should send a 403 Forbidden response to the client which should log the error to the console or record it in a log.
  • 请确保加载项清单 Scopes 部分指定了所需的全部权限。Be sure your add-in manifest Scopes section specifies all needed permissions. 此外,还请确保加载项 Web 服务注册指定了相同的权限。And be sure your registration of the add-in's web service specifies the same permissions. 同时检查是否有拼写错误。Check for spelling mistakes too. 如需了解更多信息,请参阅向 Azure AD v2.0 终结点注册加载项For more information, see Register the add-in with Azure AD v2.0 endpoint.

访问令牌(而非启动令牌)中的无效受众错误Invalid audience error in the access token (not the bootstrap token)

服务器端代码应向客户端发送 403 Forbidden 响应,向用户显示易记消息,并尽可能在控制台或日志中记录此错误。Your server-side code should send a 403 Forbidden response to the client which should present a friendly message to the user and possibly also log the error to the console or record it in a log.