Реализация единого входа для надстроек Office

  • 11 мин

Единый вход (SSO) обеспечивает удобную проверку подлинности пользователей в надстройке. С помощью этого метода надстройка может проверить подлинность пользователя для получения сведений об удостоверении или получения из другой защищенной конечной точки, например Microsoft Graph. Для этого надстройка должна вызвать серверный веб-API, зарегистрированный с помощью Идентификатора Microsoft Entra.

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

Проверка подлинности и авторизация в надстройках Office

Веб-приложения и надстройки Office по умолчанию разрешают анонимный доступ, но вы можете требовать проверку подлинности пользователей с помощью входа. Например, вы можете требовать, чтобы пользователи выполняли вход с помощью учетной записи Майкрософт, Microsoft 365 для образования, рабочей учебной записи либо другой учетной записи. Эта задача называется проверкой подлинности пользователей, так как она позволяет надстройке определить пользователя.

Ваша надстройка также может получать согласие пользователя на доступ к данным Microsoft Graph (например, к профилю Microsoft 365, файлам OneDrive и данным SharePoint) или данным в других внешних источниках, таких как Google, Facebook, LinkedIn, SalesForce и GitHub. Эта задача называется авторизацией надстройки (или приложения), так как выполняется авторизация надстройки, а не пользователя.

Можно выбрать один из двух способов выполнения проверки подлинности и авторизации.

  • Единый вход (SSO) Office. Система, которая позволяет пользователю входить в Office, чтобы также функционировать в качестве входа в надстройку. При необходимости надстройка также может использовать учетные данные пользователя Office для своей авторизации в Microsoft Graph.
  • Проверка подлинности и авторизация веб-приложений с помощью Идентификатора Microsoft Entra. Это способ, которым надстройки Office (и другие веб-приложения) проверяли подлинность пользователей и авторизованные приложения до того, как существовала система единого входа Office, и она по-прежнему используется в сценариях, когда единый вход Office не может быть. Кроме того, существуют сценарии, в которых вам может требоваться отдельный вход пользователей в вашу надстройку даже при доступности единого входа. Например, если вы хотите, чтобы у них была возможность входа в надстройку с помощью другого идентификатора, отличающегося от текущего входа в Office.

Надстройки Office и единый вход

Корпорация Майкрософт добавила поддержку единого входа для надстроек Office в 2020 г. Эта возможность снижает количество запросов пользователя на вход в сторонние службы.

Поддержка единого входа Office реализована в сочетании с кодом в пользовательских надстройках, поддержкой единого входа в пакете SDK для JavaScript для среды выполнения Office и идентификатором Microsoft Entra. Для поддержки единого входа надстройка Office должна иметь соответствующую регистрацию приложения Microsoft Entra. Эта регистрация приложения определяет, какие разрешения надстройка поддерживает и доверяет клиентским приложениям Office действовать от имени пользователя.

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

Пользователи могут самостоятельно разрешить надстройкам Office получать данные своего профиля. Затем надстройка может использовать эти сведения профиля, предоставленные Идентификатором Microsoft Entra и Office, в качестве идентификатора вошедшего в систему пользователя.

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

Единый вход надстроек Office поддерживает оба типа учетных записей, поддерживаемых корпорацией Майкрософт: рабочие и учебные учетные записи (учетные записи Microsoft Entra) и учетные записи Майкрософт (MSA).

Единый вход надстроек Office поддерживается в веб-клиентах Office и следующих клиентах для рабочего стола:

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

Общие сведения о потоке проверки подлинности единого входа

Давайте посмотрим, как работает процесс единого входа в среде выполнения.

Общая схема: процесс единого входа в среде выполнения.

  1. Код JavaScript надстройки вызывает новый API Office.js — getAccessToken(). Этот метод указывает клиентскому приложению Office, что необходимо получить маркер доступа к надстройке.
  2. Если вход в Office не выполнен, в клиентском приложении открывается всплывающее окно, в котором пользователю предлагается войти.
  3. Пользователю будет предложено предоставить согласие, если текущий пользователь впервые использует вашу надстройку.
  4. Клиентское приложение Office запрашивает маркер надстройки у конечной точки Azure AD версии 2.0 для текущего пользователя.
  5. Идентификатор Microsoft Entra отправляет маркер надстройки в клиентское приложение Office.
  6. Клиентское приложение Office отправляет маркер надстройке в составе объекта результата, возвращенного при вызове getAccessToken().
  7. JavaScript в надстройке может анализировать маркер и извлекать необходимые сведения.
  8. Кроме того, надстройка может отправить HTTP-запрос на серверную часть для получения дополнительных данных о пользователе, например, настройки пользователя. Вместо этого маркер доступа сам может быть отправлен на серверную часть для анализа и проверки.

Реализация единого входа в надстройках Office

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

  1. Регистрация приложения Microsoft Entra
  2. Связывание надстройки Office с приложением Microsoft Entra
  3. Реализация клиентского кода для получения маркера доступа из размещенного клиента Office

Рассмотрим каждую из этих действий.

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

Первым шагом является регистрация приложения Microsoft Entra для надстройки.

К приложениям Microsoft Entra, используемым для поддержки единого входа в надстройках Office, предъявляется множество требований. Например, это должны быть мультиклиентские приложения, они должны предоставлять разрешение access_as_user, а также должны доверять всем клиентским приложениям Office, вызывающим приложение.

Средства разработчика, предоставляемые корпорацией Майкрософт, включают служебную программу configure-sso , которая будет регистрировать приложение Microsoft Entra со всеми необходимыми параметрами в процессе разработки.

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

Связывание надстройки Office с приложением Microsoft Entra

После создания приложения Microsoft Entra его необходимо связать с надстройкой Office. Это делается в файле manifest.xml надстройки в разделе <WebApplicationInfo>:

<WebApplicationInfo>
  <Id>056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Id>
  <Resource>api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Resource>
  <Scopes>
    <Scope>User.Read</Scope>
    <Scope>profile</Scope>
    <Scope>openid</Scope>
  </Scopes>
</WebApplicationInfo>

Существует три части этого раздела, которые необходимо обновить для вашего приложения:

  • Идентификатор. Это идентификатор клиента зарегистрированного приложения Microsoft Entra.
  • Ресурс. Это URL-адрес надстройки, который совпадает с универсальным кодом ресурса (URI), который использовался при регистрации надстройки в Microsoft Entra ID. Доменная часть URI должна совпадать с доменом, который используется в любом из URL-адресов в разделе <Resources> файла manifest.xml надстройки.
  • Области: это разрешения или области, необходимые надстройке из идентификатора Microsoft Entra.

Важно!

Разрешения OpenID profile и openid всегда необходимы вашей надстройке. Это могут быть единственные необходимые разрешения, если надстройка не должна вызывать другую службу, например Microsoft Graph.

Кроме того, некоторым библиотекам, которые использует надстройка, могут потребоваться дополнительные разрешения. Например, MSAL.NET требуется разрешение offline_access.

Реализация клиентского кода

Наконец, надстройка должна реализовать клиентский код для реализации и поддержки единого входа. Если вы используете средства, предоставляемые корпорацией Майкрософт, ваш проект надстройки будет включать большую часть стандартного кода для поддержки единого входа. Это верно, если для надстройки ASP.NET используется Office Developer Tools для Visual Studio 2019 или генератор Yeoman для Microsoft Office для VS Code для надстройки на основе Node.js.

Метод API [OfficeRuntime.Auth.getAccessToken()](/javascript/api/office-runtime/officeruntime.auth) используется надстройкой для запроса маркера доступа у размещающего клиента Office.

Клиент Office запросит маркер доступа из Идентификатора Microsoft Entra с помощью приложения, ранее зарегистрированного в Microsoft Entra ID.

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

Использование маркера доступа для идентификации пользователя

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

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

  • name: это отображаемое имя пользователя
  • preferred_username: это имя UPN пользователя или адрес электронной почты
  • oid: это уникальный идентификатор объекта пользователя. Он должен использоваться для идентификации пользователя в серверной системе, так как свойства name и preferred_username могут быть изменены пользователем или администратором
  • tid: это уникальный ИД клиента, которому принадлежит пользователь

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

Если вы используете маркер доступа в собственном API, следует реализовать принятые рекомендации при переадресации маркера, полученного из Office. Сюда входит проверка маркера, чтобы убедиться, что он был создан идентификатором Microsoft Entra, он получен из ожидаемого центра, надстройка является целевой аудиторией маркера, срок действия маркера не истек, а область задана как access_as_user.

Использование маркера доступа для доступа к Microsoft Graph

В сценарии, в котором надстройка должна получить доступ к Microsoft Graph, код может использовать этот маркер, предоставленный Office для надстройки, для запуска потока OAuth2 on-behalf-of (OBO). Когда маркер используется таким образом, он называется "маркером начальной загрузки", так как он используется только для получения маркера доступа, который можно использовать для вызова Microsoft Graph.