M365Con 2027 – bezpłatna konferencja online · 11–22 Jan 2027 · 120 sessions→ m365con.net

Blog · Mirko Peters

Łączenie z usługą SharePoint Online za pomocą PnP PowerShell: opcje logowania

By · · Updated

Łączenie z usługą SharePoint Online za pomocą PnP PowerShell: zarejestruj własną aplikację w Microsoft Entra, a następnie wybierz logowanie interaktywne, urządzeniowe, certyfikatem lub tożsamością zarządzaną, osobno dla każdego zadania.

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

Aby połączyć się z usługą SharePoint Online za pomocą PnP PowerShell, wystarczy jednorazowo zarejestrować własną aplikację w Microsoft Entra ID. Następnie wywołujesz Connect-PnPOnline z adresem URL witryny i identyfikatorem klienta tej aplikacji oraz jedną metodą logowania: interaktywną, logowaniem urządzeniowym, certyfikatem, tożsamością zarządzaną lub starszymi poświadczeniami (legacy credentials). Ten przewodnik jest przeznaczony dla administratorów SharePoint, którzy uruchamiają skrypty ręcznie lub według harmonogramu. Wyjaśnia, co robi każda opcja, kiedy jej użyć i jakie błędy uniemożliwiają połączenie. Pokazuje również, jak wybrać jedną opcję dla każdego zadania, aby skrypt nie miał większego dostępu, niż wymaga jego zadanie.

Najważniejsze wnioski

  • Od 9 września 2024 r. Connect-PnPOnline wymaga parametru -ClientId, dlatego każdy administrator musi najpierw zarejestrować w Microsoft Entra ID aplikację, za pomocą której moduł może się logować.
  • Logowanie interaktywne jest właściwym wyborem dla osoby pracującej przy klawiaturze, ponieważ obsługuje uwierzytelnianie wieloskładnikowe i nie wymaga przechowywania sekretu.
  • Zadania uruchamiane bez udziału użytkownika powinny korzystać z logowania certyfikatem lub tożsamości zarządzanej, a nie z wpisywanego hasła ani klucza klienta zapisanego w skrypcie.
  • Przestarzała metoda z kluczem klienta (client secret) działa wyłącznie z poleceniami SharePoint, więc każde polecenie wywołujące Microsoft Graph zakończy się błędem.
  • Rejestrując aplikację, przydziel jej tylko niezbędne uprawnienia delegowane, ponieważ domyślna rejestracja żąda szerokich praw, takich jak AllSites.FullControl.

Pierwsze kroki: dlaczego każde połączenie wymaga własnej aplikacji

PnP PowerShell to moduł utrzymywany przez społeczność. Nie posiada on własnych, specjalnych uprawnień. Każde logowanie przechodzi przez rejestrację aplikacji w Microsoft Entra, a to aplikacja decyduje, co skrypt może robić.

W dokumentacji Connect-PnPOnline podano, że od 9 września 2024 r. należy podać parametr -ClientId. Wskazano też, że najpierw trzeba zarejestrować własną aplikację. Zamiast wpisywać identyfikator przy każdym połączeniu, możesz ustawić zmienną środowiskową ENTRAID_APP_ID lub ENTRAID_CLIENT_ID.

Ta zmiana dotyczy także starszych skryptów. Jeśli skrypt z 2023 r. wywołuje wyłącznie Connect-PnPOnline -Url ... -Interactive, teraz zakończy się błędem lub zażąda brakującego identyfikatora klienta. Rozwiązaniem nie jest zmiana logiki skryptu. Potrzebujesz aplikacji i jej identyfikatora.

W każdym przykładzie pojawiają się jeszcze dwie wartości:

  • -Url to adres witryny, nad którą chcesz pracować, na przykład https://contoso.sharepoint.com/sites/finance. Jest wymagany w większości metod.
  • -Tenant to nazwa dzierżawy, na przykład contoso.onmicrosoft.com. Dokumentacja wskazuje ten parametr jako wymagany dla metod z certyfikatem i odciskiem palca certyfikatu. Dla logowania interaktywnego i urządzeniowego jest opcjonalny.

Jeśli polecenie wymaga centrum administracyjnego SharePoint, możesz przekazać parametr -TenantAdminUrl. Jeśli go pominiesz, polecenia przyjmą, tam gdzie ma to zastosowanie, postać https://[nazwa_dzierżawy]-admin.sharepoint.com.

Krok 1: dokończ rejestrację aplikacji w Microsoft Entra

Ten krok wstępny zakłada, że moduł PnP.PowerShell jest już zainstalowany na Twoim komputerze. PnP udostępnia pomocnika do pierwszej konfiguracji. Strona poleceń dla Register-PnPEntraIDAppForInteractiveLogin pokazuje najkrótszą postać:

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

Otwiera się okno przeglądarki, w którym się logujesz, a polecenie tworzy aplikację. Wyświetla również identyfikator aplikacji, którego użyjesz jako -ClientId. Dodaj -DeviceLogin, jeśli na komputerze nie możesz otworzyć przeglądarki. Strona podaje, że wtedy przełączasz się na przepływ logowania urządzenia, który obsługuje uwierzytelnianie wieloskładnikowe.

Zwróć uwagę na uprawnienia. W prostym przykładzie aplikacja żąda do zatwierdzenia następujących uprawnień delegowanych: AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All i TermStore.ReadWrite.All. Drugi przykład na tej samej stronie zawęża je za pomocą -GraphDelegatePermissions "Group.Read.All" oraz -SharePointDelegatePermissions "AllSites.FullControl".

Ma to znaczenie przy zasadzie najmniejszych uprawnień. Skrypt raportujący, który tylko odczytuje dane, nie potrzebuje uprawnień zapisu dla użytkowników i grup. Ustal, czego potrzebują Twoje skrypty, i proś wyłącznie o te uprawnienia.

Prowadź notatkę o każdej rejestracji aplikacji: jej nazwa, identyfikator klienta, właściciel i posiadane uprawnienia. Przeglądaj rejestrację aplikacji raz w roku i usuń ją, gdy żaden skrypt jej już nie używa.

Warto znać dwa ograniczenia. Strona referencyjna nie podaje, jaka rola Entra jest potrzebna do rejestracji aplikacji, dlatego przed rozpoczęciem zapytaj administratora tożsamości. Parametr -SignInAudience określa, jakie typy kont obsługuje aplikacja, więc sprawdź, czy odpowiada to Twojej dzierżawie.

Jak połączyć się z SharePoint Online za pomocą PnP PowerShell: pięć opcji

Wszystkie pięć przykładów opiera się na dokumentacji Connect-PnPOnline. Zastąp wartości w nawiasach ostrokątnych.

Logowanie interaktywne

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

To domyślny wybór dla osoby. Dokumentacja podaje, że metoda ta obsługuje uwierzytelnianie wieloskładnikowe. Dodaj -ForceAuthentication, aby wyczyścić zapisane uwierzytelnienie i zalogować się innym kontem. Użyj tego, gdy przełączasz się między dzierżawą testową a produkcyjną.

Logowanie urządzenia

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

Otwiera się przeglądarka, a kod zostaje skopiowany do schowka. Wybierz tę metodę, gdy powłoka działa w sesji zdalnej, w której okno interaktywne nie sprawdza się dobrze.

Logowanie certyfikatem (aplikacja bez użytkownika)

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

Nikt się nie loguje. Aplikacja działa samodzielnie, z uprawnieniami aplikacyjnymi, które jej przydzielono. Możesz przekazać -CertificatePath wraz z -CertificatePassword, wartość -CertificateBase64Encoded lub -Thumbprint. Metoda z odciskiem palca wymaga, aby certyfikat znajdował się w magazynie certyfikatów systemu Windows. To standardowy wybór dla nienadzorowanych skryptów na serwerze.

Tożsamość zarządzana

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

Dokumentacja podaje, że ta metoda działa wyłącznie w środowiskach obsługujących tożsamości zarządzane, takich jak Azure Functions, runbooki Azure Automation czy Cloud Shell. Nie przechowujesz żadnego sekretu. W przypadku tożsamości przypisanej przez użytkownika dodaj jeden z parametrów: -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId lub -UserAssignedManagedIdentityAzureResourceId. Parametr -Url jest w tej metodzie opcjonalny.

Poświadczenia i sekrety klienta

Pozostały dwie starsze metody, a obie wiążą się z ostrzeżeniami.

  • -Credentials przyjmuje obiekt PSCredential, na przykład (Get-Credential), lub nazwę poświadczenia ogólnego w Menedżerze poświadczeń systemu Windows. Dokumentacja wymienia obsługę uwierzytelniania wieloskładnikowego dla logowania interaktywnego i logowania urządzenia, ale w tym miejscu nie składa takiej deklaracji. Traktuj tę metodę jako opcję dla kont bez monitu o logowanie i przed jej użyciem przetestuj ją.
  • -ClientSecret z -ClientId to starsza metoda ACS. Dokumentacja mówi, że przy jej użyciu „działają tylko polecenia cmdlet łączące się z SharePoint Online”. Polecenia cmdlet korzystające z Microsoft Graph zakończą się błędem.

Unikaj obu tych metod w każdym nowym rozwiązaniu. Hasło w skrypcie to ryzyko, a sekret klienta wygasa bez ostrzeżenia.

Przykład: wybór opcji logowania dla czterech zadań

Poniższe liczby i nazwy są fikcyjne i służą wyłącznie do zilustrowania przykładu.

Zespół administratorów w fikcyjnej firmie uruchamia cztery zadania. Chce mieć jedną aplikację na każdy poziom ryzyka, a nie jedną aplikację do wszystkiego.

  1. Doraźne sprawdzenia wykonywane przez administratora na laptopie. Użyj -Interactive z aplikacją, która ma wąskie uprawnienia delegowane. Administrator loguje się z uwierzytelnianiem wieloskładnikowym (MFA). Nic nie jest zapisywane.
  2. Jednorazowe czyszczenie uruchamiane na zdalnym serwerze pośredniczącym. Użyj -DeviceLogin. Administrator kończy logowanie na telefonie lub laptopie, po czym zadanie się uruchamia.
  3. Nocna inwentaryzacja na serwerze z systemem Windows. Użyj certyfikatu z -Thumbprint. Aplikacja ma uprawnienia aplikacyjne tylko do odczytu. Certyfikat jest ważny przez 12 miesięcy, a zespół wpisuje datę odnowienia do wspólnego kalendarza.
  4. Cotygodniowe zadanie w runbooku usługi Azure Automation. Użyj -ManagedIdentity. Nie ma certyfikatu ani sekretu do rotowania.

Efekt: tylko zadania 1 i 2 zależą od człowieka. Zadania 3 i 4 działają bez niczyjej obecności, a żadne z nich nie przechowuje hasła. Jeśli serwer z zadaniem 3 zostanie skradziony, zespół unieważnia jeden certyfikat. Nie musi resetować hasła administratora.

Niezależnie od wybranej opcji przechowuj adres URL witryny w zmiennej, na przykład $siteUrl. Dzięki temu jeden skrypt PowerShell może przejść przez każdą witrynę z listy, pobrać z niej potrzebne dane i przesłać raport. Przed uruchomieniem skryptu dla całej dzierżawy Microsoft 365 przetestuj go na jednej kolekcji witryn.

Częste błędy

  • Zapomnienie o -ClientId. Połączenie kończy się błędem lub system prosi o podanie identyfikatora. Na komputerach, na których często uruchamiasz skrypty, zapisz identyfikator w zmiennej środowiskowej ENTRAID_APP_ID.
  • Używanie jednej wszechmocnej aplikacji do wszystkiego. Domyślna rejestracja prosi o uprawnienia AllSites.FullControl oraz zapis do użytkowników i grup. Zarejestruj drugą aplikację, tylko do odczytu, do raportów.
  • Używanie sekretu klienta z poleceniami cmdlet opartymi na Graph. Metoda starsza działa tylko z poleceniami SharePoint. Jeśli polecenie wywołuje Graph, zakończy się błędem, a komunikat o błędzie może być mylący.
  • Umieszczanie hasła lub sekretu w pliku skryptu. Każdy, kto ma prawo odczytu tego pliku, poznaje poświadczenia. Użyj magazynu certyfikatów lub tożsamości zarządzanej.
  • Brak testu logowania w docelowym środowisku. Skrypt, który działa na laptopie z -Interactive, może zawieść na serwerze bez przeglądarki. Testuj metodą, której zadanie będzie faktycznie używać.
  • Pozostawanie zalogowanym w niewłaściwej dzierżawie. Przy zmianie konta użyj -ForceAuthentication i na początku każdego skryptu wyświetl szczegóły połączenia.

Jak oprogramowanie może pomóc

Zacznij od tego, co już masz. Moduł PnP i Microsoft Graph PowerShell SDK obejmują większość skryptów administracyjnych. Azure Automation uruchamia skrypty według harmonogramu z użyciem tożsamości zarządzanej, a centrum administracyjne SharePoint pokazuje witryny i ustawienia bez kodu. Jeśli chodzi o sekrety, magazyn certyfikatów lub magazyn kluczy jest bezpieczniejszy niż plik skryptu.

Dodaj raportowanie. Skrypt, który poprawnie się łączy, to dopiero pierwszy krok. Zespoły potrzebują też czytelnego dziennika tego, co każdy skrypt zmienił i jakiej tożsamości aplikacji użył, aby kolejny administrator mógł to prześledzić. Przechowuj ten dziennik w miejscu dostępnym dla wszystkich, na przykład na liście udostępnionej lub w systemie zgłoszeń.

Następny krok

Zarejestruj dziś jedną aplikację z najmniejszym zestawem uprawnień delegowanych, jakiego potrzebują Twoje skrypty. Następnie sprawdź, czy możesz połączyć się z SharePoint Online za pomocą PnP PowerShell z użyciem -Interactive, i zapisz, z której opcji logowania będzie korzystać każde z zaplanowanych zadań.

Obserwuj podcastSpotify

Entities in this article

PnP PowerShell Microsoft Entra PowerShell SharePoint

Related articles

RSS