Поделиться через

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

  • Статья

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

Примечание.

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

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

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

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

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

13000

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

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

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

13001

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

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

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

Эта ошибка обычно не возникает в Office в Интернете. Если срок действия файла cookie пользователя истек, Office в Интернете возвращает ошибку 13006. Однако если пользователь обращается к Outlook в Интернете из Firefox с включенной расширенной защитой от отслеживания, он столкнется с ошибкой 13001.

13002

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

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

13003

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

13004

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

13005

Недопустимое разрешение. Как правило, это означает, что приложение Office не получило предварительные разрешения для веб-службы надстройки. Дополнительные сведения см. в статье Создание приложения-службы и регистрация надстройки Office, которая использует единый вход (SSO) с помощью платформа удостоверений Майкрософт. Это также может произойти, если пользователь не предоставил приложению службы разрешения на доступ к своему ресурсу profile, или отменил согласие. Ваш код должен инициировать возврат к альтернативной системе проверки подлинности пользователя.

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

13006

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

13007

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

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 минимальная версия — версия 1911 (сборка 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 видит эту строку, он запрашивает у пользователя дополнительные факторы, а затем возвращает новый маркер доступа, который будет принят в потоке on-behalf-of.

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

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

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

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

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

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