Обзор
Несколько веб-частей Vitextra читают данные, которые находятся за пределами сайта SharePoint: профили пользователей и иерархию руководителей в Microsoft Entra ID, присутствие в Microsoft Teams, календари, задачи в Planner и To Do, файлы в OneDrive. Решения SharePoint Framework (SPFx) получают эти данные через Microsoft Graph, и администратор клиента (тенанта) Microsoft 365 должен один раз разрешить такой доступ.
Механизм одинаков для любого решения SPFx: пакет решения объявляет нужные ему разрешения, SharePoint превращает это объявление в запросы разрешений при развёртывании пакета в каталоге приложений, и запросы ожидают на странице Доступ к API Центра администрирования SharePoint, пока администратор не утвердит или не отклонит их.
В этой статье объясняется, какие продукты Vitextra запрашивают разрешения и зачем, как утвердить запросы, как позднее проверить и отозвать их и что видно в веб-частях, когда разрешение отсутствует. Статья написана для администраторов SharePoint и глобальных администраторов, которые устанавливают продукты Vitextra, а также для специалистов по безопасности, которые проверяют такие запросы.
📝 Заметка
Статья охватывает только запросы доступа к API решений SPFx. Установка самого пакета описана в статье KB10035. Как установить продукт Vitextra в SharePoint Online.
Что запрашивается и зачем
Все разрешения, запрашиваемые продуктами Vitextra, — делегированные: они действуют только в контексте вошедшего пользователя и никогда не дают веб-части доступа сверх того, что у этого пользователя уже есть в Microsoft 365. Веб-часть, которая показывает список коллег, показывает ровно тех людей и те атрибуты, которые пользователь мог бы найти в Outlook или Teams; веб-часть, которая показывает задачи, показывает задачи пользователя, открывшего страницу.
В таблице перечислены разрешения, объявленные текущими версиями продуктов, которые используют Microsoft Graph.
| Продукт | API | Разрешения | Для чего используются |
|---|---|---|---|
| Employee Directory | Microsoft Graph | User.Read.All, Directory.Read.All, People.Read, Presence.Read.All, Calendars.Read | Чтение профилей пользователей, подразделений и руководителей; связанные люди; присутствие в Teams; состояние «свободен/занят» для индикатора доступности |
| Employee Details | Microsoft Graph | User.Read.All, User.ReadWrite, People.Read.All, Presence.Read.All, Files.Read.All, Sites.Read.All, Calendars.Read.Shared | Чтение профилей; возможность пользователю изменять поля собственного профиля; связанные люди; присутствие; документы и сайты, с которыми человек недавно работал (аналитика Microsoft Graph); состояние «свободен/занят» коллег для рабочих часов и доступности |
| Organizational Chart | Microsoft Graph | User.Read.All, Directory.Read.All, Presence.Read.All | Построение иерархии подчинения по атрибуту Руководитель; подразделение и должность; присутствие в Teams |
| Absence & Coverage | Microsoft Graph | User.Read.All | Определение сотрудников, их руководителей и прямых подчинённых для заявок, согласований и замещений |
| My Tasks | Microsoft Graph | User.Read, User.ReadBasic.All, Tasks.ReadWrite | Задачи из Planner, To Do и помеченных писем; имена авторов задач |
| My Tasks | Azure DevOps | user_impersonation | Источник Azure DevOps и веб-часть Azure DevOps Query |
| Password Vault | Microsoft Graph | Files.ReadWrite.AppFolder | Хранение зашифрованного хранилища в папке приложения в OneDrive пользователя |
Продукты, которые работают только с текущим сайтом, — Announcements Carousel, List Filter Online, QR Code Generator, Questions & Answers, Quick Poll, RSS Reader, Smart Search и Smart Tiles — не запрашивают разрешений API. На странице Доступ к API для них ничего не появляется.
📝 Заметка
Имя разрешения, например Tasks.ReadWrite или User.ReadWrite, — это имя области (scope) Microsoft Graph, которая может быть шире того, что продукт с ней делает. My Tasks только читает задачи; Employee Details записывает только поля профиля вошедшего пользователя. Каждое разрешение подробно объяснено в статьях по продуктам: KB10235. Разрешения Microsoft Graph, необходимые для Organizational Chart, KB10303. My Tasks: разрешения, конфиденциальность и безопасность.
Откуда берутся запросы
Запрос разрешения создаётся при развёртывании пакета .sppkg в каталоге приложений клиента. Запросы принадлежат пакету, а не отдельным веб-частям, поэтому решение с двумя веб-частями показывает один набор запросов, а разрешение, которое нужно только необязательной функции (например, источнику Azure DevOps в My Tasks), запрашивается вместе с остальными.
Для управления важны два момента:
- Утверждение действует на весь клиент. SharePoint предоставляет разрешение одному приложению Microsoft Entra ID, которое используется для всех решений SPFx, — SharePoint Online Web Client Extensibility (ранее: SharePoint Online Client Extensibility Web Application Principal). Как только разрешение User.Read.All утверждено для Employee Directory, то же самое предоставление используется Organizational Chart и любым другим решением SPFx в клиенте, которое его запрашивает. Так устроен SharePoint Framework; это не решение Vitextra.
- Развёртывание не зависит от утверждения. Продукт Vitextra можно развернуть, добавить на сайты и разместить на страницах, пока его запросы ещё ожидают утверждения или даже отклонены. Перестают работать только функции, которые зависят от отсутствующего разрешения.
Предварительные требования
- Пакет Vitextra загружен в каталог приложений клиента и развёрнут (Включить приложение).
- Вы вошли с учётной записью, у которой есть роль Администратор SharePoint или Глобальный администратор. Администраторы семейства сайтов и владельцы каталога приложений не могут утверждать доступ к API.
❗ Важно
На странице Доступ к API показываются запросы пакетов, развёрнутых в каталоге приложений клиента. Если вы предпочитаете развёртывать продукты Vitextra из каталога приложений семейства сайтов, сначала разверните пакет в каталоге приложений клиента и утвердите запросы там; утверждённые разрешения действуют на весь клиент и затем доступны и копии в каталоге приложений семейства сайтов.
Утверждение запросов
1. Откройте Центр администрирования Microsoft 365 и перейдите в Центр администрирования SharePoint.
2. В области навигации слева разверните раздел Дополнительно и выберите Доступ к API.
3. На вкладке Ожидающие запросы найдите запросы пакета Vitextra. В каждой строке указаны имя пакета (например, Vitextra Employee Directory), API (Microsoft Graph или Azure DevOps) и разрешение.
4. Выберите запрос и кликните Утвердить. Прочитайте описание на панели и подтвердите кнопкой Утвердить.
5. Повторите для каждого запроса пакета. Разрешение, которое уже утверждено для другого решения, повторно не появляется: SharePoint использует существующее предоставление.
6. Перейдите на вкладку Утвержденные запросы и убедитесь, что все разрешения пакета в списке.
Пользователи не видят запроса согласия: после утверждения веб-части работают у всех в клиенте. Обычно предоставление вступает в силу в течение нескольких минут; если веб-часть по-прежнему сообщает об отсутствии разрешения, перезагрузите страницу или выйдите и войдите снова, чтобы получить новый токен.
💡 Совет
Запросы можно утвердить разом с помощью SharePoint Online Management Shell: Get-SPOTenantServicePrincipalPermissionRequests выводит ожидающие запросы, а Approve-SPOTenantServicePrincipalPermissionRequest -RequestId <id> утверждает один из них. Это удобно, когда вы разворачиваете несколько продуктов Vitextra одновременно.
Утверждение только части разрешений
Можно утвердить одни запросы и отклонить другие. Веб-часть продолжает работать, и страдает только зависимая функция:
- отклонено Presence.Read.All — Employee Directory, Employee Details и Organizational Chart показывают людей без индикатора присутствия Teams;
- отклонено Calendars.Read / Calendars.Read.Shared — сведения о доступности и рабочих часах не показываются;
- отклонено Files.Read.All / Sites.Read.All — Employee Details не показывает недавние файлы и сайты;
- отклонено user_impersonation (Azure DevOps) — источник Azure DevOps в My Tasks и веб-часть Azure DevOps Query не могут войти в Azure DevOps.
Отклонение основного разрешения продукта (User.Read.All для продуктов о людях, Tasks.ReadWrite для My Tasks, Files.ReadWrite.AppFolder для Password Vault) оставляет веб-часть без данных.
Что видят пользователи, когда разрешение отсутствует
| Симптом | Вероятная причина |
|---|---|
| Веб-часть показывает ошибку об отказе в доступе, недостаточных правах или отсутствии согласия | Основное разрешение ожидает утверждения или отклонено |
| Сотрудники перечислены, но цветная точка присутствия отсутствует | Не утверждено Presence.Read.All |
| Организационная структура пуста или показывает только текущего пользователя | Не утверждено User.Read.All или Directory.Read.All |
| My Tasks ничего не показывает для Planner, To Do и Outlook, а источник SharePoint работает | Не утверждено Tasks.ReadWrite |
| Всё работало, а после обновления одна функция перестала | Новая версия запрашивает дополнительное разрешение, которое ещё ожидает утверждения |
Откройте страницу Доступ к API и сравните вкладки Ожидающие запросы и Утвержденные запросы с таблицей в начале этой статьи.
Обновления и новые разрешения
Когда вы загружаете новую версию пакета (см. KB10050. Как обновить решение Vitextra на SPFx в SharePoint Online), утверждённые ранее разрешения остаются утверждёнными. Если новая версия объявляет разрешение, которого не было в предыдущей, новый запрос появляется на вкладке Ожидающие запросы и его нужно утвердить тем же способом. Vitextra перечисляет такие изменения в заметках о выпуске продукта.
Проверка и отзыв разрешений
Поскольку предоставления общие для всех решений SPFx, удаление продукта Vitextra не отзывает запрошенные им разрешения. Чтобы отозвать разрешение:
- Откройте Доступ к API и перейдите на вкладку Утвержденные запросы.
- Выберите разрешение и кликните Удалить.
- Подтвердите.
❗ Важно
Прежде чем удалять разрешение, проверьте, не зависит ли от него другое решение в клиенте: на той же вкладке находятся ваши собственные веб-части SPFx, продукты других поставщиков и предварительно авторизованные разрешения самой Microsoft. Удаление разрешения, которое использует другое решение, немедленно ломает это решение.
Отклонённый запрос можно утвердить позднее: отклонённые запросы остаются на вкладке Ожидающие запросы, пока пакет не удалён из каталога приложений. Если запрос исчез, повторное развёртывание пакета в каталоге приложений создаёт его заново.
Замечания по безопасности для проверяющих
- Каждый вызов Microsoft Graph выполняется из браузера вошедшего пользователя с токеном, выданным для этого пользователя. У веб-частей Vitextra нет разрешений приложения (app-only) и нет служебной учётной записи.
- Microsoft Graph применяет собственные разрешения пользователя поверх делегированной области: пользователь, скрытый из адресной книги, или клиент, который ограничивает API People, отражаются в веб-частях так же, как в Outlook.
- Данные каталога, задач и файлы в Vitextra не отправляются. Единственные запросы к службам Vitextra — проверка лицензии и телеметрия использования с техническими идентификаторами; см. KB10363. Где продукты Vitextra хранят ваши данные: конфиденциальность, расположение данных и GDPR.
