Упражнение. Создание надстройки Office для Word, реализующей единый вход

  • 18 мин

В этом упражнении вы создадите надстройку Word, которая вставляет сведения о пользователе, находящемся в системе в данный момент, с помощью Microsoft Graph. В этом процессе используется схема проверки подлинности с единым входом (SSO).

Предварительные требования

Для разработки надстройки Office для Microsoft Word требуется веб-клиент или следующие классические клиенты:

  • Windows версии 16.0.12215.20006 (или более поздней)
  • macOS версии 16.32.19102902 (или более поздней)

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

Важно!

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

Важно!

Это упражнение предназначено для работы с генератором Yeoman для Microsoft Office версии 1.8.8. Убедитесь, что вы используете эту версию, установив определенную версию с помощью команды npm install generator-office@1.8.8 --global. Более поздние версии генератора удалили, а затем изменили шаблон проекта единого входа, который не соответствует шагам в этой лаборатории.

Создание проекта надстройки

Выполните следующую команду, чтобы создать проект надстройки с помощью генератора Yeoman:

yo office

Примечание.

При выполнении команды yo office может появиться запрос о политиках сбора данных генератора Yeoman и средств CLI надстройки Office. Используйте предоставленные сведения, чтобы ответить на запросы подходящим образом.

При появлении запроса предоставьте следующую информацию для создания проекта надстройки:

  • Выберите тип проекта: проект надстройки Office в области задач с поддержкой единого входа
  • Выберите тип сценария: JavaScript
  • Как вы хотите назвать свою надстройку? MyWordSsoAddin
  • Какое клиентское приложение Office должно поддерживаться? Word

Снимок экрана с запросами и ответами в генераторе Yeoman.

После ответов на вопросы генератор создаст проект и установит вспомогательные компоненты Node.

Знакомство с исходным проектом

Все проекты надстроек Word включают в себя различные папки и файлы, которые реализуют надстройку для Microsoft Word. Надстройка в основном реализована в папках ./src/commands и ./src/taskpane. Файлы в этих двух папках реализуют базовую надстройку области задач и необязательные команды для запуска надстройки.

Рассмотрим некоторые другие файлы, добавленные в проект, которые поддерживают реализацию единого входа для пользователей. Эти файлы можно найти в папке ./src/helpers.

  • documentHelper.js. Этот файл использует библиотеку API JavaScript для Office для получения данных из Microsoft Graph и добавления их в документ Word.
  • fallbackauthdialog.html. Этот файл представляет собой страницу без пользовательского интерфейса, которая загружает JavaScript для резервной стратегии проверки подлинности.
  • fallbackauthdialog.js. Этот файл содержит JavaScript для стратегии проверки подлинности, который использует библиотеку проверки подлинности Майкрософт для JavaScript (MSAL.js) для входа пользователя.
  • fallbackauthhelper.js. Этот файл содержит JavaScript для области задач, который вызывает резервную стратегию проверки подлинности в сценариях, если проверка подлинности с помощью единого входа не поддерживается.
  • ssoauthhelper.js. Этот файл содержит JavaScript, который вызывает API единого входа getAccessToken(), получает маркер начальной загрузки и инициирует его замену на маркер доступа, который можно использовать для вызова Microsoft Graph. Он также содержит код для вызова конечной точки Microsoft Graph.

Важно!

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

Рекомендация по системе безопасности: всегда используйте серверный код для выполнения вызовов Microsoft Graph или других вызовов, требующих передачи маркера доступа. Никогда не возвращайте маркер OBO клиенту, чтобы клиент мог выполнять прямые вызовы в Microsoft Graph. Это помогает защитить маркер от перехвата или утечки. Дополнительные сведения о правильном потоке протокола см. на схеме протокола OAuth 2.0.

Регистрация приложения Azure Active Directory (Azure AD)

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

Прежде чем протестировать проект, необходимо зарегистрировать приложение Azure AD, а затем обновить проект для использования приложения Azure AD.

Совет

Дополнительные сведения о регистрации приложения Azure AD вручную см. в статье Создание надстройки Office Node.js, использующей единый вход: регистрация надстройки в конечной точке Azure AD версии 2.0.

Проект надстройки Office включает служебную программу, которая может создавать регистрацию приложения Azure AD и обновлять проект.

С помощью командной строки убедитесь, что вы находитесь в корневой папке проекта. Затем выполните следующую команду:

npm run configure-sso

Команда запустит браузер и предложит выполнить вход в Azure AD. Убедитесь, что вы выполняете вход как пользователь с разрешениями на регистрацию приложения Azure AD, например, как пользователь, которому назначена роль глобального администратора.

После проверки подлинности сценарий выполнит следующие задачи:

  1. Регистрация приложения Azure AD
  2. Настройка аудитории приложения и параметров разрешений
  3. Создание нового секрета клиента и его сохранение в хранилище секретов на рабочих станциях разработчиков
  4. Обновление проекта с помощью идентификатора клиента приложения Azure AD

Снимок экрана: результат запуска сценария configure-sso.

Предупреждение

Команда configure-sso не будет работать, если клиент Azure AD настроен для многофакторной или двухфакторной проверки подлинности. В этом случае вам потребуется вручную создать регистрацию приложения Azure AD согласно инструкциям в статье Создание надстройки Office Node.js, использующей единый вход: регистрация надстройки в конечной точке Azure AD версии 2.0.

Рассмотрим работу сценария configure-sso.

Откройте браузер и перейдите в Центр администрирования Azure Active Directory (https://aad.portal.azure.com). Войдите с помощью рабочей или учебной учетной записи с правами глобального администратора для клиента.

Выберите Azure Active Directory на панели навигации слева.

Регистрация приложения

Выберите Управление>Регистрация приложений на панели навигации слева.

Снимок экрана: регистрация приложений на портале Центра администрирования Azure Active Directory.

На странице Регистрация приложений выберите приложение MyWordSsoAddin. Это название приложения, которое вы создали с помощью генератора Yeoman для Microsoft Office.

На странице MyWordSsoAddin обратите внимание на ИД приложения. Сценарий configure-sso, который создал приложение Azure AD, установил следующее значение в файле .ENV вашего проекта:

CLIENT_ID=056b1e8c-747d-4b45-94b1-f61ac2c19a5e
GRAPH_URL_SEGMENT=/me
NODE_ENV=development
PORT=3000
QUERY_PARAM_SEGMENT=
SCOPE=User.Read

Проверка подлинности

Затем на панели навигации слева выберите Управление>Проверка подлинности. Обратите внимание, что URI перенаправления настроены на страницы taskpane.html и fallbackauthdialog.html в нашем приложении.

Снимок экрана: раздел URI перенаправления.

Также обратите внимание, что раздел Неявные разрешения и гибридные потоки обновлен, чтобы гарантировать, что Azure AD возвращает маркеры доступа и маркеры ИД при проверке подлинности пользователя в приложении:

Снимок экрана: выбор неявного разрешения и гибридных потоков.

Сертификаты и секреты

Затем на панели навигации слева выберите Управление>Проверка подлинности. Обратите внимание, что URI перенаправления находятся в левой области навигации выберите Управление>секретами сертификатов&.

Сценарий configure-sso создал секрет клиента для приложения. Как вы видели ранее, это было отображено в командной строке, и было добавлено секретное хранилище рабочей станции разработчика.

Разрешения API

На панели навигации слева выберите Управление>Разрешения API. Обратите внимание, что для приложения настроено несколько делегированных разрешений. Сценарий console-sso также предоставил согласие администратора всем пользователям в клиенте, чтобы им не предлагалось дать согласие приложению при первом использовании приложения.

Снимок экрана: настроенные и предоставленные приложению разрешения.

Доступ к API: URI идентификатора приложения

На панели навигации слева выберите Управление>Предоставление доступа к API. На этой странице необходимо обратить внимание на несколько особенностей.

Во-первых, обратите внимание на URI идентификатора приложения. Это уникальный ИД приложения. Обратите внимание, что он содержит идентификатор приложения в полной строке.

Доступ к API: области, определенные API

Следующий раздел содержит области, определенные API. Это могут быть настраиваемые области, которые позволяют ограничить доступ к данным и функциям, защищенным API. В нашем случае приложение configure-sso добавило следующую область:

api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e/access_as_user

ИД области будет соответствовать ИД приложения. Обратите внимание на окончание области. Область access_as_user позволяет клиентским приложениям Office использовать веб-API надстройки с теми же правами, что и пользователь, вошедший в систему.

Доступ к API: авторизованные клиентские приложения

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

Это позволяет классическим и веб-приложениям Office вызывать API надстройки.

Перечислены следующие приложения:

  • Microsoft Office: d3590ed6-52b3-4102-aeff-aad2292ab01c
  • Microsoft Office: ea5a67f6-b6f3-4338-b240-c655ddc3cc8e
  • Office в Интернете: 57fb890c-0dab-4253-a5e0-7188c88b2bb4
  • Office в Интернете: 08e18876-6177-487e-b8b5-cf950c1e598c
  • Outlook в Интернете: bc59ab01-8403-45c6-8796-ac3ef710b3e3

Если выбрать одно из этих приложений, каждое из них имеет область, определенное ранее как авторизованное область.

Снимок экрана: ИД и авторизованные клиенты, которым предоставлен доступ к API надстройки.

Создание и тестирование приложения

Чтобы транскомпилировать и запустить процесс отладки, выполните следующую команду из командной строки:

npm start

Сценарий запуска совершит три действия:

  1. сборка проекта надстройки
  2. запуск локального веб-сервера для размещения надстройки на локальной рабочей станции
  3. запуск клиента Office и загрузка в него надстройки Office

Совет

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

Тестирование надстройки в клиенте Word для рабочего стола

Через некоторое время Word загрузится с кнопкой надстройки в ленте и в области задач.

Снимок экрана: надстройка в Word.

Чтобы протестировать надстройку, нажмите кнопку Получить сведения о моем профиле пользователя.

Если вы еще не вошли в систему с помощью клиента Office, вам будет предложено сделать это.

Снимок экрана: вход в Word.

После входа пользователя надстройка получит основные сведения профиля из Microsoft Graph и добавит их в документ.

Снимок экрана: успешное тестирование в Word.

Тестирование надстройки в веб-клиенте Word

Чтобы увидеть, как работает единый вход, попробуйте надстройку в веб-клиенте Office из OneDrive.

Откройте браузер и перейдите в OneDrive (https://onedrive.com). Войдите с помощью рабочей или учебной учетной записи.

Чтобы добавить новый документ Word, нажмите кнопку Создать, а затем выберите Документ Word.

Установите надстройку Word, используя загрузку неопубликованного приложения. На ленте выберите Вставка>Надстройки.

В диалоговом окне Надстройки Office выберите Отправить мою надстройку.

Выберите файл manifest.xml в корневой папке проекта и нажмите Отправить.

Microsoft Word загрузит неопубликованную надстройку и отобразит кнопку Показать область задач в ленте, как и в клиенте для рабочего стола.

Выберите кнопку Показать область задач, а затем кнопку Получить сведения о моем профиле пользователя.

Так как вы уже вошли в систему, через некоторое время вы увидите те же данные профиля в документе без необходимости входа.

Знакомство с проектом

Теперь давайте посмотрим, как надстройка Word использует единый вход для подключения к Microsoft Graph и отображения в документе сведений о профиле пользователя, находящегося в данный момент в системе.

Откройте проект, созданный в начале этого упражнения, в Visual Studio Code.

Найдите и откройте файл ./manifest.xml. В манифесте надстройки найдите элемент SourceLocation:

<OfficeApp>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:{PORT}/taskpane.html"/>
  </DefaultSettings>
</OfficeApp>

Значение в этом элементе сообщает размещающему клиенту Office URL-адрес для загрузки в IFRAME области задач.

Найдите и откройте файл ./src/taskpane/taskpane.html. В этом файле необходимо обратить внимание на две особенности.

  1. В разделе <head> страницы обратите внимание на ссылку <script> на файл office.js. Это пакет SDK JavaScript для Office, который надстройка может использовать для связи с ведущим клиентом Office.
  2. Прокрутите в конец файла до кнопки <button id="getGraphDataButton">. Это кнопка, которая запускает процесс получения маркера доступа для пользователя, чтобы запросить из Microsoft Graph сведения о профиле пользователя, находящегося в системе.

Найдите и откройте файл ./src/taskpane/taskpane.js. После того, как размещающий клиент Office загружает надстройку, он присоединяет метод ssoAuthHelper.getGraphData() к событию нажатия кнопки области задач.

Найдите и откройте файл ./src/helpers/ssoauthhelper.js. Этот файл содержит код, который делает большую часть работы по проверке подлинности пользователя с помощью единого входа и получению данных профиля пользователя из Microsoft Graph. Все это реализовано в методе getGraphData(). Метод выполняет следующие действия:

  1. Вход пользователя путем получения маркера доступа из Azure AD. Этот маркер доступа, который называется bootstrapToken, содержит маркер ИД и маркер доступа.

  2. Обмен маркера доступа с Azure AD на маркер, который можно использовать для вызова Microsoft Graph.

    Маркер bootstrapToken, полученный на первом этапе, не содержит необходимых областей для вызова Microsoft Graph, так как он используется для проверки подлинности пользователя и получения маркера идентификации.

    Примечание.

    Вызываемый на этом этапе метод sso.getGraphToken() вызывает конечную точку https://graph.microsoft.com/v1.0/auth для получения маркера доступа, который можно использовать для Microsoft Graph.

  3. Отправка HTTP-запроса в REST API Microsoft Graph для получения данных профиля пользователя. Для этого вызывается метод sso.makeGraphApiCall().

    Примечание.

    Метод sso.makeGraphApiCall() вызывает конечную точку https://graph.microsoft.com/v1.0/getuserdata для получения сведений о профиле пользователя.

Если в какой-то момент процесс проверки подлинности завершается сбоем, код использует резервный процесс проверки подлинности с помощью файлов ./src/helpers/fallbackauth*.* .

Код, добавленный генератором Yeoman для Microsoft Office в первоначальный проект надстройки, получает сведения о профиле пользователя из Microsoft Graph. В других упражнениях этого модуля показано, как запрашивать дополнительные сведения из Microsoft Graph.

Проверка знаний

1.

Процесс единого входа может получать маркер доступа, который может использоваться для вызова Microsoft Graph.

2.

Чтобы процесс единого входа работал с надстройками Office, пользователь должен предварительно войти в свою личную учетную запись либо в свою рабочую или учебную учетную запись Azure AD.

3.

Какие разрешения может запрашивать клиент Office у пользователя при первом входе пользователя из надстройки?