Поток OAuth маркера контекста для надстроек SharePoint
В SharePoint поток проверки подлинности и авторизации OAuth для размещаемой у поставщика надстройки с низким уровнем доверия включает ряд взаимодействий между надстройкой, SharePoint, сервером авторизации и браузером во время выполнения. В этом сценарии сервером авторизации является служба контроля доступа Microsoft Azure (ACS).
Важно!
Служба контроля доступа Azure (ACS), которая входит в состав Azure Active Directory (Azure AD), будет упразднена 7 ноября 2018 г. Это не влияет на модель надстроек SharePoint, использующую имя узла https://accounts.accesscontrol.windows.net (на который также не влияет это прекращение работы службы). Дополнительные сведения см. в статье Влияние упразднения службы контроля доступа Azure на надстройки SharePoint.
В размещаемой у поставщика надстройке есть удаленное веб-приложение или служба, отделенные от SharePoint и не входящие в состав фермы SharePoint или области клиентов SharePoint Online. Их можно размещать в облаке или на локальном сервере. В этой статье удаленный компонент называется Contoso.com.
Примечание.
В удаленном компоненте также могут размещаться приемники событий, которые реагируют на события, происходящие с элементами SharePoint, такими как списки и их элементы. К примерам удаленных событий, на которые может реагировать Contoso.com, относятся события со списками (например, добавление или удаление элемента) и сайтами (например, добавление или удаление сайта). Дополнительные сведения о том, как создавать удаленные приемники событий, см. в статье Создание удаленного приемника событий в надстройках SharePoint.
Contoso.com использует CSOM SharePoint или интерфейсы REST API SharePoint для вызова SharePoint. Приложение Contoso.com использует поток передачи токенов OAuth для проверки подлинности в SharePoint. SharePoint и Contoso.com не доверяют друг другу, но доверяют службе контроля доступа и принимают выданные ею маркеры.
Используется три маркера: SharePoint требует от службы контроля доступа Azure создать токен контекста, который затем пересылает Constoso.com. Contoso.com проверяет, что токен был создан службой контроля доступа, и поэтому доверяет ему. Затем Contoso.com извлекает маркер обновления из токена контекста и получает с его помощью маркер доступа непосредственно из ACS. Приложение включает маркер доступа во все свои запросы к SharePoint. SharePoint проверяет, является ли ACS поставщиком маркера, а затем отвечает на запросы от Contoso.com.
В удаленном компоненте необходимо добавить код для обработки токенов (но если удаленный компонент размещен на платформе .NET, то инструменты Microsoft Visual Studio Office Developer Tools автоматически добавляют образец кода, выполняющий большую часть работы). Дополнительные сведения о коде обработки токенов см. в статье Обработка маркеров безопасности в надстройках SharePoint с низким уровнем доверия, размещаемых у поставщика.
Предварительные требования
Чтобы надстройка SharePoint могла использовать поток токена контекста, необходимо выполнить указанные ниже предварительные действия.
Следующие требования применяются только при установке локальной надстройки SharePoint в дополнение к SharePoint Online. Эти требования не применяются, если вы устанавливаете надстройку SharePoint только в SharePoint Online
- Необходимо настроить ферму для поддержки надстроек. На самом деле это необходимо для установки любых надстроек SharePoint в ферме, даже если они не используют поток токена контекста. Дополнительные сведения см. в статье Средства и среды для разработки надстроек SharePoint.
- У пользователя, устанавливающего надстройку, должна быть учетная запись Office 365. Это необходимо для доступа к ACS. Пользователь не обязан применять свою учетную запись для каких-либо других целей.
- Ферма должна быть настроена на участие в отношениях доверия между Office 365 и ACS. Это легко сделать с помощью скриптов Windows PowerShell. Дополнительные сведения см. в статье Использование сайта SharePoint Office 365 для авторизации размещаемых у поставщика надстроек на локальном сайте SharePoint.
Независимо от того, установлена ли надстройка в SharePoint Online или локальной ферме SharePoint, надстройка SharePoint должна быть зарегистрирована в ACS. Подробные сведения о том, как это сделать, см. в статье Регистрация надстроек SharePoint. Помимо прочего, в ходе регистрации надстройка предоставляет службе контроля доступа свои идентификатор и секрет клиента.
Этапы потока токена контекста
На приведенном ниже рисунке показан поток проверки подлинности и авторизации OAuth для надстроек SharePoint, размещаемых у поставщика.
Поток маркеров контекста OAuth
Вот этапы, соответствующие номерам на рисунке.
Пользователь запускает Надстройка SharePoint из SharePoint. Способ запуска зависит от того, как спроектирована надстройка.
- Если надстройка должна предоставлять удаленное веб-приложение (на сайте Contoso.com) в веб-части надстройки (которая фактически представляет собой оболочку для объекта IFRAME), то для запуска надстройки достаточно перейти на страницу SharePoint, содержащую веб-часть надстройки. Если пользователь еще не выполнил вход, SharePoint предлагает ему войти. SharePoint обрабатывает страницу и обнаруживает на ней компонент из приложения Contoso.com. Дополнительные сведения о веб-частях надстроек см. в статье Создание веб-частей надстройки для установки с надстройкой SharePoint.
- Если надстройка рассчитана на использование в качестве полной страницы в браузере, то для ее запуска пользователь должен выбрать плитку надстройки на странице Контент сайта на веб-сайте SharePoint. Возможна вариация этого сценария, когда надстройка включает настраиваемое меню или элемент ленты для запуска удаленного компонента.
Независимо от того, как запускается надстройка, среде SharePoint необходимо получить маркер контекста, который она может отправить приложению Contoso.com. Поэтому она отправляет службе контроля доступа запрос на создание токена контекста, содержащего сведения о контексте SharePoint, в том числе о текущем пользователе и URL-адресе удаленного приложения, а также другие сведения. Токен контекста также содержит зашифрованный маркер обновления.
ACS подписывает токен контекста с помощью алгоритма, использующего секрет надстройки Contoso.com, и возвращает его в SharePoint. Этот секрет знают только ACS и надстройка Contoso.com.
Если в веб-части надстройки предоставляется доступ к приложению Contoso.com, SharePoint отрисовывает страницу, на которой размещена веб-часть надстройки, и добавляет токен контекста к URL-адресу, который объект IFRAME в веб-части надстройки вызывает для получения содержимого. Если приложение Contoso.com является полностраничным, SharePoint перенаправляет браузер на сайт Contoso.com и включает токен контекста в отклик о перенаправлении.
Токен контекста включается в запрос браузера, отправляемый на сервер Contoso.com.
Сервер Contoso.com получает токен контекста и проверяет подпись, так как ему известен секрет клиента. Это подтверждает для приложения Contoso.com факт выдачи токена службой контроля доступа, а не мошенником, действующим от имени SharePoint. Contoso.com извлекает маркер обновления из токена контекста и отправляет его (вместе с другими сведениями, включая идентификатор и секрет клиента) службе контроля доступа в запросе на получение маркера доступа к SharePoint.
Служба контроля доступа проверяет маркер обновления и, убедившись, что он был создан ею, возвращает маркер доступа Contoso.com. При необходимости Contoso.com может кэшировать этот маркер доступа, чтобы не обращаться к ACS каждый раз, когда требуется доступ к SharePoint. По умолчанию срок действия маркеров доступа составляет несколько часов. На момент написания этой статьи срок действия маркеров доступа к SharePoint, выданных службой контроля доступа, составлял 12 часов, но он может измениться.
Каждый маркер доступа связан с учетной записью, указанной в исходном запросе на авторизацию, и предоставляет доступ только к тем службам (в данном случае SharePoint), которые указаны в этом запросе. Маркеры обновления действуют дольше (шесть месяцев на момент написания этой статьи), и их также можно кэшировать. Таким образом, один и тот же маркер обновления можно менять на новый маркер доступа от ACS, пока не истечет срок действия маркера обновления. Дополнительные сведения о кэшировании маркеров см. в статье Обработка маркеров безопасности в надстройках SharePoint с низким уровнем доверия, размещаемых у поставщика.
По истечении срока действия маркера обновления Contoso.com может получить новый маркер, запросив новый токен контекста. Дополнительные сведения см. в разделе Получение нового токена контекста.
- Приложение Contoso.com использует маркер доступа для вызова REST API SharePoint или запроса CSOM к spnv. Для этого оно передает маркер доступа OAuth в заголовке HTTP Authorization. Если ваш удаленный компонент размещен на платформе .NET, то в инструментах Visual Studio Office Developer Tools вы найдете пример кода для создания заголовка.
- SharePoint проверяет маркер доступа, чтобы убедиться, что он был выдан ACS. Затем он отправляет данные, которые Contoso.com запрошены для Contoso.com или выполняет операцию создания, чтения, обновления или удаления (CRUD), которая Contoso.com запрошена.
- Страница надстройки Contoso.com преобразовывается для просмотра в браузере (или в объекте IFRAME веб-части надстройки).