Проверка подлинности и авторизация с помощью Dialog API для Office

Всегда используйте API Dialog для Office с целью проверки подлинности и авторизации пользователей с помощью надстройки Office. Если вы реализуете резервную проверку подлинности, если единый вход (SSO) не удается использовать, необходимо также использовать API диалогового окна Office.

Надстройки Office запускаются в iframe при открытии в Office в Интернете. Многие центры идентификации, также называемые службами secure Token Services (STS), не позволяют открывать страницу входа в iframe. К ним относятся Google, Facebook и службы, защищенные платформой удостоверений Майкрософт (ранее Azure AD версии 2.0), такие как учетная запись Майкрософт, microsoft 365 для образовательных учреждений или рабочая учетная запись или другая общая учетная запись. Кроме того, функции безопасности, реализованные в веб-представлении при запуске надстроек Office в Office в Windows или Office на Mac, могут препятствовать правильной работе страниц входа.

Чтобы авторизация работала правильно, страница входа должна открыться в отдельном браузере или экземпляре элемента управления WebView. Именно поэтому Office предоставляет API диалогового окна Office, в частности метод displayDialogAsync .

Диалоговое окно, открытое с помощью этого API, имеет следующие характеристики.

• Оно не модальное.
• Это полностью отдельный экземпляр браузера в области задач. Это означает следующее:
  • Он имеет собственную среду выполнения, объект окна и глобальные переменные.
  • Не существует общей среды выполнения с областью задач.
  • Он не имеет общего хранилища сеансов (свойство Window.sessionStorage ), что и область задач.
• Первая страница, открытая в диалоговом окне, должна размещаться в том же домене, что и область задач, включая протокол, поддомены и порт, если таковые есть.
• Диалоговое окно может отправлять сведения обратно в область задач с помощью метода messageParent . Рекомендуется вызывать этот метод только на странице, размещенной в том же домене, что и область задач, включая протокол, поддомены и порт. В противном случае с вызовом метода и обработкой сообщения могут возникать сложности. Дополнительные сведения см. в разделе Междоменные сообщения в основной среде выполнения.

По умолчанию диалоговое окно открывается в новом элементе управления веб-представления, а не в iframe. Это гарантирует, что откроется страница входа поставщика удостоверений. Как вы увидите далее в этой статье, характеристики диалогового окна Office влияют на использование библиотек проверки подлинности или авторизации, таких как библиотека проверки подлинности Майкрософт (MSAL) и Passport.

Поток проверки подлинности с помощью диалогового окна Office

Ниже описан типичный поток проверки подлинности.

1. Первая страница, открывающаяся в диалоговом окне, — это страница (или другой ресурс), размещенный в домене надстройки; то есть тот же домен, что и окно области задач. Эта страница может иметь пользовательский интерфейс, в котором написано только "Подождите, мы перенаправляем вас на страницу, где вы можете войти в NAME-OF-PROVIDER". Код на этой странице создает URL-адрес страницы входа поставщика удостоверений со сведениями, которые либо передаются в диалоговое окно, как описано в разделе Передача сведений в диалоговое окно , либо жестко закодирован в файл конфигурации надстройки, например файл web.config.
2. Затем диалоговое окно перенаправляет пользователя на страницу входа. URL-адрес включает параметр запроса, который дает указание поставщику удостоверений после входа пользователя перенаправить последнего на определенную страницу. В этой статье мы назовем эту страницу redirectPage.html. На этой странице результаты попытки входа можно передать в область задач с помощью вызова messageParent. Рекомендуется использовать страницу в том же домене, что и основное окно.
3. Служба поставщика удостоверений обрабатывает входящий запрос GET, поступивший из диалогового окна. Если пользователь уже вошел в систему, она немедленно перенаправляет его на страницу redirectPage.html и включает пользовательские данные в параметр запроса. Если пользователь еще не вошел, в окне появляется страница поставщика для входа. Для большинства поставщиков, если пользователь не может выполнить вход, поставщик отображает страницу ошибки в диалоговом окне и не перенаправляет на redirectPage.html. Пользователь должен закрыть это окно, нажав кнопку X в углу. Если пользователь успешно входит, он перенаправляется на страницу redirectPage.html, а пользовательские данные добавляются в параметр запроса.
4. Когда открывается страница redirectPage.html, она вызывает функцию messageParent, чтобы сообщить о результате в область панели задач, а также сообщить пользовательские данные или данные об ошибке. Она также может передавать маркер доступа или сообщать в область задач, что маркер находится в хранилище.
5. На странице области задач запускается событие DialogMessageReceived, и его обработчик закрывает диалоговое окно и может дальше обрабатывать сообщение.

Поддержка нескольких поставщиков удостоверений

Если надстройка предоставляет пользователю выбор поставщиков, таких как учетная запись Майкрософт, Google или Facebook, вам потребуется локальная первая страница (см. предыдущий раздел), которая предоставляет пользователю пользовательский интерфейс для выбора поставщика. Выбор активирует создание URL-адреса входа и перенаправление на него.

Авторизация надстройки через внешний ресурс

В современном Интернете пользователи и веб-приложения являются субъектами безопасности. У приложений есть свои удостоверения и разрешения для онлайн-ресурсов, таких как Microsoft 365, Google+, Facebook и LinkedIn. Перед развертыванием приложение регистрируется у поставщика ресурса. Регистрация включает:

• Список разрешений, которые нужны приложению.
• URL-адрес, на который служба ресурса должна возвращать маркер доступа, когда приложение получает доступ к службе.

Когда пользователь вызывает функцию в приложении, которое получает доступ к его данным в службе ресурса, пользователю будет предложено войти в службу, а затем предоставить приложению необходимые разрешения. Служба затем перенаправляет пользователя на зарегистрированный URL-адрес и передает маркер доступа. Приложение использует маркер доступа для доступа к ресурсам пользователя.

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

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

Примеры проверки подлинности в надстройках, использующих Dialog API для Office, приводятся в разделе Примеры.

Использование библиотек проверки подлинности с диалоговым окном

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

Как правило, для хранения маркеров нельзя использовать внутренний кэш библиотеки.

Обычно библиотеки проверки подлинности хранят маркер доступа в кэше в памяти. При последующих обращениях к поставщику ресурсов (например, Google, Microsoft Graph, Facebook и т. д.) библиотека сначала проверит, действителен ли маркер в кэше. Если срок его действия не истек, библиотека возвращает кэшированный маркер и не совершает повторно круговой путь в STS за новым маркером. Но этот шаблон не используется в надстройках Office. Так как процесс входа выполняется в экземпляре браузера диалогового окна Office, кэш маркеров находится в этом экземпляре.

Кроме того, библиотека обычно предоставляет как интерактивные, так и автоматические методы для получения маркера. Если вы выполняете проверку подлинности и звонки для передачи данных в ресурс в одном экземпляре браузера, код вызывает автоматический метод, чтобы получить маркер непосредственно перед добавлением его в звонок для передачи данных. Автоматический метод проверяет, есть ли в кэше действительный маркер, и возвращает его. В противном случае автоматический метод вызывает интерактивный метод, который перенаправляет на вход службы stS. После завершения входа интерактивный метод возвращает маркер, но также кэширует его в памяти. Но если используется Dialog API для Office, вызовы данных из ресурса, которые должны вызывать автоматический метод, находятся в экземпляре браузера в области задач. Кэш маркеров библиотеки не существует в этом экземпляре.

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

Кроме того, можно передать маркер в область задач, используя messageParent метод. Это можно сделать только в том случае, если интерактивный метод сохранил маркер доступа в таком расположении, в котором код может прочитать его. Иногда интерактивный метод работы библиотеки сохраняет маркер в частном свойстве объекта, недоступном для вашего кода.

Обычно нельзя использовать объект "контекста проверки подлинности" библиотеки.

Часто библиотека проверки подлинности использует метод, позволяющий получить маркер в интерактивном режиме, а также создать объект в контексте проверки подлинности, возвращаемый методом. Маркер — это свойство объекта (которое может быть частным и недоступным непосредственно из кода). У этого объекта есть методы получения данных из ресурса. Они включают маркер в HTTP-запросах, которые они выполняют к поставщику ресурсов (например, Google, Microsoft Graph, Facebook и т. д.).

Эти объекты контекста проверки подлинности и методы, которые их создают, недоступны для использования в надстройках Office. Так как вход выполняется в экземпляре браузера диалогового окна Office, объект должен быть создан там. Но данные, поступающие в ресурс, находятся в экземпляре браузера в области задач, и вам не удастся передать объект из одного экземпляра в другой. Например, невозможно передать объект методом messageParent, так как messageParent может передавать только строковые значения. Объект JavaScript, содержащий методы, нельзя надежно преобразовать в строку.

Использование библиотек с помощью Dialog API для Office

Большинство библиотек в дополнение к монолитным объектам в контексте проверки подлинности или вместо них обеспечивает API более низкого уровня абстракции, разрешая коду создавать менее монолитные вспомогательные объекты. Например, MSAL.NET v. 3.x.x.x есть API для создания URL-адреса входа и другой API, который создает объект AuthResult, содержащий маркер доступа в свойстве, доступном вашему коду. Примеры MSAL.NET в надстройке Office см. в статьях Надстройка Office в Microsoft Graph ASP.NET и Надстройка Outlook в Microsoft Graph ASP.NET. Пример использования msal.js в надстройке см. в статье Надстройка Office в Microsoft Graph React.

Дополнительные сведения о библиотеках проверки подлинности и авторизации см. в статьеMicrosoft Graph — Рекомендуемые библиотеки и Другие внешние службы: библиотеки.

Примеры

• Надстройка Office в Microsoft Graph ASP.NET — это надстройка на основе ASP.NET (Excel, Word или PowerPoint), использующая библиотеку MSAL.NET и поток кода авторизации для входа и получения маркера доступа к данным Microsoft Graph.
• Надстройка Outlook в Microsoft Graph ASP.NET — это такая же надстройка, как описано выше, но относящаяся к приложению Outlook.
• Надстройка Office в Microsoft Graph React — это надстройка на основе NodeJS (Excel, Word или PowerPoint), использующая библиотеку msal.js и неявный поток для входа и получения маркера доступа к данным Microsoft Graph.

См. также

• Авторизация внешних служб в надстройке Office
• Использование Dialog API для Office в надстройках Office