M365Con 2027 – бесплатная онлайн-конференция · 11–22 Jan 2027 · 120 sessions→ m365con.net

Блог · Mirko Peters

Подключение к SharePoint Online с помощью PnP PowerShell: варианты входа

By · · Updated

Подключение к SharePoint Online с помощью PnP PowerShell: зарегистрируйте собственное приложение Entra, затем для каждой задачи выбирайте интерактивный вход, вход по коду устройства, сертификат или управляемое удостоверение.

Automatically translated with AI from the original post. Read the English original

Чтобы подключиться к SharePoint Online с помощью PnP PowerShell сегодня, сначала один раз зарегистрируйте собственное приложение в Microsoft Entra ID. Затем вызывайте Connect-PnPOnline с URL вашего сайта, идентификатором клиента этого приложения и одним из способов входа: интерактивным, по коду устройства, с сертификатом, управляемым удостоверением или устаревшими учётными данными. Это руководство предназначено для администраторов SharePoint, которые запускают скрипты вручную или по расписанию. Оно объясняет, что делает каждый вариант, когда его использовать и какие ошибки мешают подключению. Также показано, как выбрать один вариант для каждой задачи, чтобы скрипту не требовалось больше доступа, чем нужно для его работы.

Ключевые выводы

  • С 9 сентября 2024 года для Connect-PnPOnline нужен параметр -ClientId, поэтому каждый администратор сначала должен зарегистрировать в Microsoft Entra ID приложение, с помощью которого модуль может войти.
  • Интерактивный вход — правильный выбор для человека за клавиатурой, так как он поддерживает многофакторную аутентификацию и не требует сохранённого секрета.
  • Задачи без участия пользователя должны использовать вход по сертификату или управляемое удостоверение, а не введённый пароль и не клиентский секрет, сохранённый в скрипте.
  • Устаревший метод с клиентским секретом работает только для командлетов SharePoint, поэтому любая команда, которая обращается к Microsoft Graph, с ним завершится ошибкой.
  • Регистрируйте приложение только с нужными делегированными разрешениями, так как регистрация по умолчанию запрашивает широкие права, например AllSites.FullControl.

Начало работы: зачем каждому подключению собственное приложение

PnP PowerShell — модуль, который поддерживает сообщество. Особых прав у него нет. Каждый вход проходит через регистрацию приложения в Microsoft Entra, и это приложение определяет, что может делать скрипт.

В справочнике Connect-PnPOnline сказано, что с 9 сентября 2024 года нужно указывать параметр -ClientId. Там же говорится, что сначала необходимо зарегистрировать собственное приложение. Вместо того чтобы вводить идентификатор каждый раз, можно задать переменную окружения ENTRAID_APP_ID или ENTRAID_CLIENT_ID.

Это затронуло старые скрипты. Если скрипт 2023 года вызывает Connect-PnPOnline -Url ... -Interactive и больше ничего, теперь он завершится ошибкой или запросит отсутствующий ClientId. Исправление не в логике скрипта. Нужны приложение и его идентификатор.

Во всех примерах встречаются ещё два значения:

  • -Url — адрес сайта, с которым вы работаете, например https://contoso.sharepoint.com/sites/finance. Обязателен для большинства способов входа.
  • -Tenant — имя клиента, например contoso.onmicrosoft.com. В справочнике указано, что он обязателен для способов с сертификатом и отпечатком. Для интерактивного входа и входа по коду устройства он необязателен.

Если команде нужен центр администрирования SharePoint, можно передать -TenantAdminUrl. Если его не указать, командлеты там, где это применимо, используют адрес вида https://[tenantname]-admin.sharepoint.com.

Шаг 1: завершите регистрацию приложения в Microsoft Entra

Этот шаг предполагает, что модуль PnP.PowerShell уже установлен на вашем компьютере. PnP предоставляет вспомогательную команду для первоначальной настройки. На странице справки по командлету Register-PnPEntraIDAppForInteractiveLogin приведена самая короткая форма:

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com

Открывается окно браузера, в котором нужно войти в систему, и командлет создает приложение. Он также выводит идентификатор приложения, который вы будете использовать как -ClientId. Добавьте -DeviceLogin, если на компьютере не получается открыть браузер. На странице сказано, что это переключает на сценарий входа по коду устройства, который поддерживает многофакторную аутентификацию.

Обратите внимание на разрешения. В простом примере приложение запрашивает для согласия следующие делегированные разрешения: AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All и TermStore.ReadWrite.All. Второй пример на той же странице ограничивает их с помощью -GraphDelegatePermissions "Group.Read.All" и -SharePointDelegatePermissions "AllSites.FullControl".

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

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

Есть два ограничения, о которых нужно знать. На справочной странице не указано, какая роль Entra нужна для регистрации приложения, поэтому уточните это у администратора идентификации до начала работы. Кроме того, параметр -SignInAudience определяет, какие типы учетных записей поддерживает приложение, поэтому проверьте, что он соответствует вашему клиенту.

Как подключиться к SharePoint Online с помощью PnP PowerShell: пять вариантов

Все пять примеров используют справку по Connect-PnPOnline в качестве источника. Замените значения в угловых скобках.

Интерактивный вход

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>

Это вариант по умолчанию для пользователя. В справке сказано, что он рассчитан на поддержку многофакторной аутентификации. Добавьте -ForceAuthentication, чтобы очистить сохраненную аутентификацию и войти под другой учетной записью. Используйте этот параметр, когда переключаетесь между тестовым и рабочим клиентом.

Вход по коду устройства

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>

Открывается браузер, а код копируется в буфер обмена. Выбирайте этот вариант, когда оболочка работает в удаленном сеансе, где интерактивное окно работает неудобно.

Вход по сертификату (только приложение)

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>

Никто не входит в систему. Приложение действует самостоятельно, с теми разрешениями приложения, которые вы ему выдали. Можно передать -CertificatePath вместе с -CertificatePassword, значение -CertificateBase64Encoded или -Thumbprint. Для способа с отпечатком сертификат должен находиться в хранилище сертификатов Windows. Это стандартный выбор для автоматических скриптов на сервере.

Управляемое удостоверение

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity

В справке сказано, что этот способ работает только в средах, поддерживающих управляемые удостоверения, например в Azure Functions, runbook-ах Automation и Cloud Shell. Секрет при этом не хранится вообще. Для пользовательского управляемого удостоверения добавьте один из параметров: -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId или -UserAssignedManagedIdentityAzureResourceId. С этим способом параметр -Url необязателен.

Учетные данные и клиентские секреты

Остаются два более старых способа, и оба сопровождаются предупреждениями.

  • -Credentials принимает объект PSCredential, например (Get-Credential), или имя универсальных учетных данных в Диспетчере учетных данных Windows. В справке перечислена поддержка многофакторной аутентификации для интерактивного входа и входа по коду устройства, но здесь такого утверждения не делается. Рассматривайте этот способ как вариант для учетных записей без запроса и проверьте его перед тем, как на него полагаться.
  • -ClientSecret вместе с -ClientId — это устаревший метод ACS. В справке сказано, что с ним "работают только командлеты, которые подключаются к SharePoint Online". Командлеты, которые используют Microsoft Graph, завершатся с ошибкой.

Не используйте ни один из этих методов для нового. Пароль в скрипте — это риск, а клиентский секрет истекает без предупреждения.

Пример: выбор варианта входа для четырёх задач

Числа и названия ниже вымышленные и приведены для иллюстрации.

Административная команда вымышленной компании выполняет четыре задачи. Им нужно одно приложение на каждый уровень риска, а не одно приложение для всего.

  1. Разовые проверки администратором за ноутбуком. Используйте -Interactive с приложением, у которого узкие делегированные разрешения. Администратор входит с MFA. Ничего не сохраняется.
  2. Однократная очистка на удалённом jump-сервере. Используйте -DeviceLogin. Администратор завершает вход на телефоне или ноутбуке, и выполнение запускается.
  3. Ночная инвентаризация на сервере Windows. Используйте сертификат с -Thumbprint. У приложения есть разрешения приложения только на чтение. Сертификат действителен 12 месяцев, и команда вносит дату продления в общий календарь.
  4. Еженедельная задача в runbook Automation. Используйте -ManagedIdentity. Нет сертификата или секрета, которые нужно было бы ротировать.

Итог: от человека зависят только задачи 1 и 2. Задачи 3 и 4 выполняются без присутствия кого-либо, и ни одна из них не хранит пароль. Если сервер задачи 3 украдут, команда отзывает один сертификат. Им не нужно сбрасывать пароль администратора.

Какой бы вариант вы ни выбрали, храните URL сайта в переменной, например $siteUrl, чтобы один скрипт PowerShell мог перебирать каждый сайт из списка, получать нужные данные с каждого сайта SharePoint и загружать отчёт. Перед запуском по всему клиенту Microsoft 365 протестируйте скрипт на одной коллекции сайтов.

Распространённые ошибки

  • Забытый -ClientId. Подключение не удаётся или запрашивает его. Сохраняйте ID в переменной среды ENTRAID_APP_ID на машинах, где часто запускаете скрипты.
  • Использование одного всемогущего приложения для всего. Регистрация по умолчанию запрашивает AllSites.FullControl и доступ на запись к пользователям и группам. Зарегистрируйте второе приложение только для чтения для отчётов.
  • Использование клиентского секрета с командлетами на основе Graph. Устаревший метод работает только с командлетами SharePoint. Если команда обращается к Graph, она завершится с ошибкой, и сообщение об ошибке может сбить с толку.
  • Помещение пароля или секрета в файл скрипта. У любого, кто имеет доступ на чтение к файлу, есть учётные данные. Используйте хранилище сертификатов или управляемую идентичность.
  • Непроверка входа в конечной среде. Скрипт, который работает на вашем ноутбуке с -Interactive, может не работать на сервере без браузера. Тестируйте тем методом, который задача будет использовать на самом деле.
  • Оставание в не том клиенте. Используйте -ForceAuthentication, когда переключаете учётные записи, и выводите параметры подключения в начале каждого скрипта.

Как может помочь программное обеспечение

Начните с того, что у вас уже есть. Модуль PnP и Microsoft Graph PowerShell SDK покрывают большую часть административных скриптов. Azure Automation запускает скрипты по расписанию с управляемой идентичностью, а центр администрирования SharePoint показывает сайты и параметры без кода. Для секретов хранилище сертификатов или Key Vault безопаснее, чем файл скрипта.

Добавьте отчётность поверх этого. Скрипт, который корректно подключается, — только первый шаг. Команде также нужен понятный журнал того, что изменил каждый скрипт и какую идентичность приложения он использовал, чтобы следующий администратор мог во всём разобраться. Храните журнал там, где его могут прочитать все, например в общем списке или системе заявок.

Следующий шаг

Сегодня зарегистрируйте одно приложение с минимально необходимым набором делегированных разрешений для ваших скриптов. Затем проверьте, что можете подключиться к SharePoint Online через PnP PowerShell с -Interactive, и запишите, какой вариант входа будет использовать каждая из ваших запланированных задач.

Подписаться на подкастSpotify

Entities in this article

PnP PowerShell Microsoft Entra PowerShell SharePoint

Related articles

RSS