Поделиться через

Изолированные веб-части

  • Статья

Эта возможность позволяет создавать веб-части, которые устанавливают безопасную связь с API, защищенными с помощью Microsoft Azure AD, без использования маркера доступа для других компонентов на странице или даже сценариев в клиенте.

Зачем использовать изолированные веб-части

Чтобы позволить решениям SharePoint Framework осуществлять безопасный доступ к API, защищенным с помощью Microsoft Azure AD, вы можете использовать управление API, чтобы указать, какие API смогут использоваться сценариями в вашем клиенте и с какими разрешениями. Затем с помощью SharePoint Framework вы сможете легко восстановить маркер доступа для определенных API. Хотя это значительно упрощает установление связи с API, защищенными с помощью Microsoft Azure AD, это также позволяет всем сценариям, а не только отдельным решениям SharePoint Framework, получить маркер доступа для любого из утвержденных API. Если один из сценариев, используемых в вашем клиенте, оказался уязвим для атаки, он сможет получить доступ к любому из утвержденных API от имени текущего пользователя.

Изолированные веб-части представляют собой новый способ изоляции доступа к API, защищенным с помощью Microsoft Azure AD, и гарантируют, что только определенные веб-части SharePoint Framework смогут получить маркер доступа для определенного API.

Как работают использованные веб-части

Важно!

Изолированные веб-части доступны в SharePoint Framework 1.8 и более поздних версиях. Изолированные веб-части поддерживаются только на современных страницах. Хотя вы можете добавить изолированные веб-части на классические страницы, после публикации веб-часть не будет отображаться и создавать ошибку. Изолированные веб-части можно установить только в каталоге приложений клиента. Они не будут работать из каталога приложений семейства веб-сайтов.

Описание архитектуры, иллюстрирующее принцип работы изолированных веб-частей

Решения, использующие возможность изолированных веб-частей, имеют определенный флаг, установленный в метаданных проекта в файле *.sppkg . При развертывании таких решений в каталоге приложений все запросы на получение разрешений для API указываются как изолированные.

После одобрения изолированного запроса разрешений для API SharePoint создаст отдельное приложение Microsoft Azure AD в Azure AD, связанное с клиентом Microsoft 365. Это приложение Microsoft Azure AD будет привязано к конкретному решению SharePoint Framework, которое запрашивает разрешение для API, и будет иметь набор разрешений OAuth, запрашиваемый данным решением. Обратный URL-адрес приложения Microsoft Azure AD, который используется скрытым потоком OAuth, будет задан для уникального домена, связанного с определенным приложением SharePoint Framework.

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

Шаблон проекта, использующий изолированные разрешения

При создании шаблона нового проекта SharePoint Framework, который ориентирован на SharePoint Online, генератор Yeoman для SharePoint Framework отобразит следующую подсказку:

Потребуются ли компонентам решения уникальные разрешения на доступ к веб-API, не используемые другими компонентами в клиенте?:

Если ответить Да, генератор добавит к конфигурации вашего проекта флаг в файле config/package-solution.json, настроив для свойства isDomainIsolated значение true. Так как изоляция распространяется только на веб-части, генератор позволяет создавать только веб-части в вашем проекте.

Важно!

Теоретически вы можете вручную создать расширение SharePoint Framework в проекте, который использует изолированные разрешения. Тем не менее это плохая идея, и вам никогда не следует делать этого и она не поддерживается.

Если расширение, которые вы добавили, установит связь с API, защищенным с помощью Microsoft Azure AD, оно не сможет получить маркер доступа в изолированном виде и произойдет сбой во время выполнения.

Осуществление связи с API

Несмотря на то что веб-части используют изолированные разрешения, получение маркера доступа для API, защищенного с помощью Azure AD, в коде программы выполняется стандартным образом. Кроме того, несмотря на то что во время выполнения изолированные веб-части будут загружены в iframe, указывающем на уникальный домен, вы можете установить связь с SharePoint REST API тем же образом, что и при использовании неизолированных веб-частей.

Развертывание решений с изолированными веб-частями

Решения с изолированными веб-частями развертываются таким же образом, что и стандартные решения SharePoint Framework. Единственное отличие заключается в том, что запросы разрешения для API являются изолированными. Это хорошо видно на странице управления API, где запросы разрешения для API сгруппированы для конкретного решения, для которого они применяются.

Разрешения API, полученные на уровне клиента, могут использоваться любым решением SharePoint Framework или отрывком кода на уровне клиента. Изолированные разрешения, с другой стороны, могут использоваться только решением, которое их запрашивает.

Использование изолированных веб-частей

При добавлении на страницу изолированные веб-части отображаются с помощью iframe. Этот iframe указывает на уникальный домен, назначенный для решения SharePoint Framework, где находится веб-часть. Данный домен также указан в обратном URL-адресе приложения Microsoft Azure AD, созданного для размещения изолированных разрешений для определенного решения SharePoint Framework. С помощью уникального домена можно гарантировать, что только веб-части определенного решения SharePoint Framework смогут получить маркер доступа для изолированного набора разрешений.

Панель свойств для изолированных веб-частей

Панель свойств для изолированных веб-частей отображается как отдельный iframe с дополнительнымэкземпляром той же веб-части. Он содержит некоторые особенности, о которых следует знать разработчикам:

  • События жизненного цикла изолированной веб-части, такие как render будут вызываться дважды: один раз для самой веб-части и один раз для области свойств.
  • Размер iframe панели свойств ограничен размерами панели. Примите это во внимание, если вы планируете использовать модальные окна или любые широкие элементы управления на панели свойств.

Утилизация изолированных веб-частей

onDispose метод для изолированных веб-частей нельзя вызывать, так как удаление iframe из DOM автоматически очищает все ресурсы, включая соединения сокетов, связанные с документом iframe.

Обновление существующего проекта с использованием изолированных разрешений

Если вы обновляете существующий проект до версии 1.8.0 SharePoint Framework и хотите использовать изолированные разрешения, вы можете сделать это, присвоив в файле config/package-solution.json свойству isDomainIsolated значение true. Убедитесь, что проект содержит только веб-части.

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

Удаление решений с изолированными разрешениями

При одобрении изолированных разрешений для API SharePoint создает выделенное приложение Microsoft Azure AD для конкретного решения SharePoint Framework, которое запрашивает разрешения. При удалении из каталога приложений решения SharePoint Framework разрешения для API, а также приложение Azure AD, не удаляются.