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

  • 11 мин

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

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

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

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

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

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

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

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

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

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

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

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

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

Служба единого входа надстройки Office поддерживает оба типа учетных записей, поддерживаемых Корпорацией Майкрософт: рабочие и учебные учетные записи (учетные записи Azure AD) и учетные записи Майкрософт (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. Azure AD отправляет маркер надстройки клиентскому приложению Office.
  6. Клиентское приложение Office отправляет маркер надстройке в составе объекта результата, возвращенного при вызове getAccessToken().
  7. JavaScript в надстройке может анализировать маркер и извлекать необходимые сведения.
  8. Кроме того, надстройка может отправить HTTP-запрос на серверную часть для получения дополнительных данных о пользователе, например, настройки пользователя. Вместо этого маркер доступа сам может быть отправлен на серверную часть для анализа и проверки.

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

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

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

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

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

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

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

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

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

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

После создания приложения Azure AD оно должно быть связано с надстройкой 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>

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

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

Важно!

Разрешения 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 запросит маркер доступа из Azure AD с помощью приложения, ранее зарегистрированного в Azure AD.

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

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

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

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

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

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

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

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

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