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 і більше нічого, тепер він завершиться помилкою або запитає відсутній ідентифікатор клієнта. Виправлення стосується не логіки скрипту. Потрібні застосунок і його ідентифікатор.

В усіх прикладах з'являються ще два значення:

  • -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), або назву Generic Credential у Диспетчері облікових даних Windows. Довідка вказує підтримку багатофакторної автентифікації для інтерактивного входу та входу з пристрою, але тут цього не стверджує. Сприймайте це як варіант для облікових записів без запиту та перевірте перед використанням.
  • -ClientSecret разом із -ClientId — це застарілий метод ACS. У довідці сказано, що з ним «працюватимуть лише командлети, які підключаються до SharePoint Online». Командлети, що використовують Microsoft Graph, завершуватимуться помилкою.

Уникайте обох варіантів для всього нового. Пароль у скрипті — це ризик, а клієнтський секрет спливає без попередження.

Приклад: вибір варіанта входу для чотирьох завдань

Числа й назви нижче вигадані для ілюстрації.

Адміністративна команда вигаданої компанії виконує чотири завдання. Вона хоче мати один застосунок для кожного рівня ризику, а не один застосунок для всього.

  1. Разові перевірки адміністратором за ноутбуком. Використовуйте -Interactive із застосунком, який має вузькі делеговані дозволи. Адміністратор входить з MFA. Нічого не зберігається.
  2. Одноразове очищення на віддаленому сервері-переході. Використовуйте -DeviceLogin. Адміністратор завершує вхід на телефоні або ноутбуці, і виконання починається.
  3. Щоnічна інвентаризація на сервері 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, вона завершиться помилкою, і повідомлення про помилку може бути заплутаним.
  • Розміщення пароля або секрету у файлі скрипта. Будь-хто з доступом на читання до файлу отримує облікові дані. Використовуйте сховище сертифікатів або керовану identity.
  • Не перевірка входу в кінцевому середовищі. Скрипт, який працює на вашому ноутбуці з -Interactive, може завершитися помилкою на сервері без браузера. Тестуйте тим методом, яким завдання реально використовуватиме.
  • Залишення в неправильному клієнті. Використовуйте -ForceAuthentication, коли перемикаєте облікові записи, і виводьте дані підключення на початку кожного скрипта.

Як може допомогти програмне забезпечення

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

Додайте звітність. Скрипт, який правильно підключається, — лише перший крок. Команді також потрібен зрозумілий журнал того, що змінив кожен скрипт і яку identity застосунку він використовував, щоб наступний адміністратор міг це простежити. Зберігайте журнал там, де його зможе прочитати кожен, наприклад у спільному списку або системі заявок.

Наступний крок

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

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

Entities in this article

PnP PowerShell Microsoft Entra PowerShell SharePoint

Related articles

RSS