Сценарий: реализация единого входа для службы в надстройке Outlook

  • Статья

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

Примечание.

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

Зачем использовать маркер доступа с единым входом?

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

  • Маркер единого входа представлен в стандартном формате OpenID и выдается службой Azure. Это значительно упрощает проверку таких маркеров. С другой стороны, для маркеров удостоверений Exchange используется специальный формат, основанный на стандарте JSON Web Token, поэтому для проверки маркера требуются дополнительные действия.
  • Маркер единого входа можно использовать во внутренней службе для получения маркера доступа к Microsoft Graph. При этом пользователю не требуется выполнять дополнительных действий для входа.
  • Маркер единого входа предоставляет больше сведений об удостоверении, например отображаемое имя пользователя.

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

В этом примере рассматривается надстройка, состоящая из пользовательского интерфейса и скриптов (HTML и JavaScript), а также внутреннего веб-API, вызываемого надстройкой. Внутренний веб-API вызывает как API Microsoft Graph, так и API данных Contoso — вымышленный API от стороннего разработчика. Как и API Microsoft Graph, API данных Contoso требует проверку подлинности OAuth. Необходимо, чтобы внутренний веб-API мог вызывать оба API, не запрашивая учетные данные пользователя каждый раз, когда истекает срок действия маркера доступа.

Для этого внутренний API создает надежную базу данных пользователей. Каждому пользователю соответствует запись в базе данных, где внутренняя служба может хранить долговечные маркеры обновления для API Microsoft Graph и API данных Contoso. Приведенная ниже разметка JSON представляет запись пользователя в базе данных.

{
  "userDisplayName": "...",
  "ssoId": "...",
  "exchangeId": "...",
  "graphRefreshToken": "...",
  "contosoRefreshToken": "..."
}

Надстройка включает маркер доступа для единого входа (если этот токен доступен) или маркер удостоверения Exchange (если маркер единого входа недоступен) при каждом вызове внутреннего веб-API.

Запуск надстройки

  1. При запуске надстройка отправляет запрос внутреннему веб-API, чтобы определить, зарегистрирован ли пользователь (т. е. связана ли с ним запись в базе данных пользователей) и есть ли в API маркеры обновления для Graph и Contoso. В данные этого вызова надстройка включает как маркер единого входа (если этот токен доступен), так и маркер удостоверения.

  2. Веб-API использует методы из статей Проверка подлинности пользователя с помощью маркера единого входа в надстройке Outlook и Проверка подлинности пользователя с помощью маркера удостоверения для Exchange для проверки и создания уникального идентификатора из обоих маркеров.

  3. Если маркер единого входа предоставлен, веб-API отправляет в базу данных пользователей запрос записи, где значение ssoId совпадает с уникальным идентификатором, созданным из маркера единого входа.

    • Если такая запись не существует, надстройка переходит к следующему этапу.
    • Если запись существует, надстройка переходит к этапу 5.

  4. Веб-API запрашивает из базы данных запись, где значение exchangeId совпадает с уникальным идентификатором, созданным из маркера удостоверения Exchange.

    • Если такая запись существует и маркер единого входа был предоставлен, запись пользователя в базе данных обновляется — свойству ssoId присваивается значение уникального идентификатора, созданного из маркера единого входа, после чего надстройка переходит к этапу 5.
    • Если запись существует, а маркер единого входа не предоставлен, надстройка переходит к этапу 5.
    • Если запись не существует, создается новая запись. Свойству ssoId присваивается значение уникального идентификатора на основе маркера единого входа (если этот токен доступен), а свойству exchangeId — значение уникального идентификатора на основе маркера удостоверения Exchange.

  5. В значении graphRefreshToken выполняется поиск действительного маркера обновления.

    • Если значение отсутствует или не является действительным, а маркер единого входа был предоставлен, используется поток "от имени" OAuth2 для получения маркеров доступа и обновления для Graph. Маркер обновления сохраняется в значении graphRefreshToken для пользователя.

  6. Проверяется наличие действительных маркеров обновления в graphRefreshToken и contosoRefreshToken.

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

  7. Надстройка проверяет отклик.

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

Авторизация внутреннего веб-API

В идеале процедура авторизации внутреннего веб-API для вызова API Microsoft Graph и API данных Contoso должна выполняться только один раз, после чего пользователю не будет предлагаться войти.

В зависимости от того, каков отклик от внутреннего веб-API, надстройке может потребоваться авторизовать пользователя для API Microsoft Graph, API данных Contoso или обоих интерфейсов. Так как оба API используют проверку подлинности OAuth2, для них используются похожие способы.

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

  2. По завершении потока надстройка отправляет маркер обновления внутреннему веб-API, включив маркер единого входа (если этот токен доступен) или маркер удостоверения Exchange.

  3. Внутренний веб-API находит пользователя в базе данных и обновляет соответствующий маркер обновления.

  4. Надстройка возобновляет работу в обычном режиме.

Обычная работа

Каждый раз, когда надстройка вызывает внутренний веб-API, она включает в вызов либо маркер единого входа, либо маркер удостоверения Exchange. Внутренний веб-API находит пользователя по этому токену, а затем использует сохраненные маркеры обновления, чтобы получить маркеры доступа для API Microsoft Graph и API данных Contoso. Пока маркеры обновления действительны, пользователю не придется повторно выполнять вход.