Устранение ошибок единого входа

  • Статья

В этой статье представлено руководство по обеспечению надежной обработки специальных условий и ошибок в надстройках Office, поддерживающих единый вход, а также устранению связанных с единым входом проблем в таких надстройках.

Примечание.

API единого входа в настоящее время поддерживается для Word, Excel, Outlook и PowerPoint. Дополнительные сведения о текущей поддержке API единого входа см. в статье Наборы обязательных элементов API идентификации. Если вы работаете с надстройкой Outlook, обязательно включите современную проверку подлинности для клиента Microsoft 365. Сведения о том, как это сделать, см. в статье Включение или отключение современной проверки подлинности для Outlook в Exchange Online.

Средства отладки

Настоятельно рекомендуем использовать во время разработки средство, которое может перехватывать и отображать HTTP-запросы от веб-службы надстройки и отклики для нее. Из них наиболее популярны следующие средства:

Причины и обработка ошибок в методе getAccessToken

Примеры обработки ошибок, рассматриваемых в этом разделе:

13000

Надстройка или версия Office не поддерживает API getAccessToken.

  • Эта версия Office не поддерживает единый вход. Требуемая версия — подписка На Microsoft 365 в любом ежемесячном канале.
  • В манифесте надстройки отсутствует подходящий раздел WebApplicationInfo.

Ваша надстройка должна отреагировать на эту ошибку, переключившись на альтернативную систему проверки подлинности пользователя. Дополнительные сведения см. в разделе Требования и рекомендации.

13001

Пользователь не вошел в Office. В большинстве сценариев эту ошибку следует предотвращать, не допуская ее повторения, путем передачи элемента allowSignInPrompt: true в параметре AuthOptions.

Но могут быть исключения. Например, вы хотите, чтобы надстройка открывалась с функциями, для которых требуется вход пользователя в систему, но только в том случае, если пользователь уже вошел в Office. В противном случае надстройку следует открыть с помощью альтернативного набора функций, которые не требуют входа пользователя в систему. В этом случае логика выполняется при запуске надстройкой вызовов getAccessToken без allowSignInPrompt: true. Используйте ошибку 13001 в качестве пометки, чтобы указать надстройке представить альтернативный набор функций.

Другая возможность — реагирование на ошибку 13001, с переключением на альтернативную систему проверки подлинности пользователя. Это обеспечит вход пользователя в AAD, но не вход пользователя в Office.

Эта ошибка никогда не возникает в Office в Интернете. Если срок действия cookie-файла пользователя истек, Office в Интернете возвращает ошибку 13006.

13002

Пользователь прервал вход или отменил свое согласие (например, выбрав Отмена в диалоговом окне согласия).

  • Если ваша надстройка предоставляет функции, не требующие входа пользователя (или предоставления согласия), то в коде следует отслеживать эту ошибку и позволять надстройке продолжать работу.
  • Если для надстройки требуется пользователь, который вошел в систему и получил согласие, в вашем коде должна появиться кнопка входа в систему.

13003

Тип пользователя не поддерживается. Пользователь не входит в Office с помощью действующей учетной записи Майкрософт, Microsoft 365 для образования или рабочей учетной записи. Например, это может произойти, если Office работает с учетной записью локального домена. Ваш код должен инициировать возврат к альтернативной системе проверки подлинности пользователя. В Outlook эта ошибка также может возникнуть, если современная проверка подлинности отключена для клиента пользователя в Exchange Online. Дополнительные сведения см. в разделе Требования и рекомендации.

13004

Недопустимый ресурс. (Эта ошибка должна быть замечена только при разработке.) Манифест надстройки настроен неправильно. Обновите манифест. Дополнительные сведения см. в статье Проверка манифеста надстройки Office. Наиболее распространенная проблема заключается в том, что <элемент Resource> (в элементе <WebApplicationInfo> ) имеет домен, который не соответствует домену надстройки. Хотя часть протокола значения ресурса должна быть "api", а не "https", все остальные части доменного имени (включая порт, если таковой имеется) должны быть такими же, как и для надстройки.

13005

Недопустимое разрешение. Как правило, это означает, что приложение Office не получило предварительные разрешения для веб-службы надстройки. Дополнительные сведения см. в разделе Создание приложения службы и статье Регистрация надстройки в конечной точке Azure AD версии 2.0. Это также может произойти, если пользователь не предоставил приложению службы разрешения на доступ к своему ресурсу profile, или отменил согласие. Ваш код должен инициировать возврат к альтернативной системе проверки подлинности пользователя.

Другая возможная причина при разработке заключается в том, что ваша надстройка использует Internet Explorer, и вы используете самозаверяющий сертификат. (Чтобы определить, какой браузер или веб-представление используется надстройкой, см. статью Браузеры и элементы управления webview, используемые надстройками Office.)

13006

Ошибка клиента. Эта ошибка возникает только в Office в Интернете. Код должен предлагать пользователю выйти и затем перезапустить сеанс браузера для Office.

13007

Приложению Office не удалось получить маркер доступа к веб-службе надстройки.

  • Если эта ошибка возникает во время разработки, убедитесь, что в регистрационных данных и манифесте надстройки указаны разрешение profile (и разрешение openid, если вы используете MSAL.NET). Дополнительные сведения см. в статье Регистрация надстройки с помощью конечной точки Azure AD версии 2.0.
  • В рабочей среде несоответствие учетных записей может вызвать эту ошибку. Например, если пользователь пытается войти с помощью личной учетной записи Майкрософт (MSA), когда ожидалась рабочая или учебная учетная запись. В таких случаях код должен вернуться к альтернативной системе проверки подлинности пользователей. Дополнительные сведения о типах учетных записей см. в статье Удостоверения и типы учетных записей для приложений с одним и несколькими клиентами.

13008

Пользователь запустил операцию, которая вызывает метод getAccessToken, до завершения предыдущего вызова метода getAccessToken. Эта ошибка возникает только в Office в Интернете. Код должен предлагать пользователю повторить операцию после завершения предыдущей операции.

13010

Пользователь запускает надстройку в Office в Microsoft Edge. Домен Microsoft 365 пользователя и login.microsoftonline.com домен находятся в других зонах безопасности в параметрах браузера. Эта ошибка возникает только в Office в Интернете. Если возвращается эта ошибка, то пользователь уже видел сообщение с соответствующим пояснением и ссылкой на инструкции по изменению конфигурации зон. Если ваша надстройка предоставляет функции, не требующие входа пользователя, то в коде следует отслеживать эту ошибку и позволять надстройке продолжать работу.

13012

Существует несколько возможных причин.

  • Надстройка выполняется на платформе, которая не поддерживает API getAccessToken. Например, она не поддерживается на iPad. См. также наборы обязательных элементов API удостоверений.
  • Документ Office был открыт на вкладке Файлы канала Teams с помощью параметра Изменить в Teams в раскрывающемся меню Открыть . API getAccessToken не поддерживается в этом сценарии.
  • Параметр forMSGraphAccess был передан в вызов getAccessToken, и пользователь получил надстройку через AppSource. В этом сценарии администратор клиента не предоставил надстройке согласие на области Microsoft Graph (разрешения), которые ей нужны. При отзыве getAccessToken с помощью allowConsentPrompt проблема не будет устранена, так как для Office допускается предложить пользователю разрешение только для области profile AAD.

Ваш код должен инициировать возврат к альтернативной системе проверки подлинности пользователя.

В процессе разработки надстройка является неопубликованной в Outlook, а параметр forMSGraphAccess передается в вызов getAccessToken.

13013

Вызывается getAccessToken слишком много раз за короткий промежуток времени, поэтому Office регулирует последний вызов. Обычно это вызвано бесконечным циклом вызовов метода . Существуют сценарии, когда рекомендуется отозвать метод. Однако код должен использовать переменную счетчика или флага, чтобы убедиться, что метод не отозван повторно. Если тот же путь кода "повторить" выполняется снова, код должен вернуться к альтернативной системе проверки подлинности пользователей. Пример кода см. в статье Использование переменной retryGetAccessToken в HomeES6.js или ssoAuthES6.js.

50001

Эта ошибка (нехарактерная для getAccessToken) может указывать, что браузер поместил в кэш старую копию файлов office.js. Во время разработки очистите кэш браузера. Другой возможный вариант — версия Office устарела и не поддерживает единый вход. В Windows минимальная сборка — 16.0.12215.20006. На Mac это 16.32.19102902.

Если надстройка выполняется в рабочей среде, она должна отреагировать на эту ошибку, переключившись на альтернативную систему проверки подлинности пользователя. Дополнительные сведения см. в разделе Требования и рекомендации.

Ошибки на стороне сервера из Azure Active Directory

Примеры обработки ошибок, рассматриваемых в этом разделе:

Ошибки условного доступа и многофакторной проверки подлинности

В некоторых конфигурациях удостоверений в AAD и Microsoft 365 некоторые ресурсы, доступные с помощью Microsoft Graph, могут требовать многофакторную проверку подлинности (MFA), даже если клиент Microsoft 365 этого не делает. Когда служба AAD получает запрос на получение токена для доступа к защищенному с помощью MFA ресурсу, через поток выполнения от имени другого субъекта она возвращает веб-службе надстройки сообщение JSON, содержащее свойство claims. Свойство claims содержит сведения о том, какие еще факторы проверки подлинности требуются.

Ваш код должен выполнить проверку на это свойство claims. В зависимости от архитектуры надстройки вы можете протестировать ее на стороне клиента, а также на стороне сервера и ретранслировать ее клиенту. Эти сведения необходимы клиенту, так как Office обрабатывает проверку подлинности для надстроек с единым входом. Если вы ретранслируете ее со стороны сервера, сообщение для клиента может быть кодом ошибки (например, 500 Server Error или 401 Unauthorized) либо находиться в тексте отклика об успешном выполнении (например, 200 OK). В обоих случаях функция обратного вызова для клиентского AJAX-вызова веб-API надстройки должна проверять этот отклик.

Независимо от архитектуры, если значение утверждений отправлено из AAD, код должен отозвать getAccessToken и передать параметр authChallenge: CLAIMS-STRING-HERE в параметре options . Когда служба AAD обнаруживает эту строку, она предлагает пользователю указать дополнительные факторы, а затем возвращает новый маркер доступа, который будет принят в потоке выполнения от имени другого субъекта.

Если в службе AAD нет записи о том, что пользователь или администратор клиента согласился предоставить надстройке доступ к ресурсу Microsoft Graph, то AAD отправит вашей веб-службе сообщение об ошибке. Код должен сообщить клиенту (например, в тексте отклика 403 Forbidden).

Если для надстройки требуются области Microsoft Graph, которые могут предоставляться только администратором, код должен возвращать ошибку. Если пользователь может дать согласие только на те области, которые ему нужны, ваш код должен инициировать возврат к альтернативной системе проверки подлинности пользователя.

Ошибки, вызванные недействительными или отсутствующими областями (разрешениями)

Эта ошибка возникает только в процессе разработки.

  • Код на стороне сервера должен отправить отклик 403 Forbidden клиенту, который должен записать ошибку в консоли или журнале.
  • Убедитесь, что в разделе Scopes манифеста надстройки указаны все необходимые разрешения. Кроме того, убедитесь, что в регистрационных данных веб-службы надстройки указаны те же разрешения. Кроме того, проверьте наличие ошибок правописания. Дополнительные сведения см. в статье Регистрация надстройки с помощью конечной точки Azure AD версии 2.0.

Недопустимая ошибка аудитории в маркере доступа для Microsoft Graph

Код на стороне сервера должен отправить отклик 403 Forbidden клиенту, а тот должен показать пользователю понятное сообщение и, возможно, также записать ошибку в консоли или журнале.