Verbinding maken met SharePoint Online via PnP PowerShell: aanmeldopties
By Mirko Peters · · Updated
Verbinding maken met SharePoint Online via PnP PowerShell: registreer je eigen Entra-app en kies per taak interactief aanmelden, apparaatcode, certificaat of beheerde identiteit.
Automatically translated with AI from the original post. Read the English original
Om vandaag via PnP PowerShell verbinding te maken met SharePoint Online, registreer je één keer een eigen app in Microsoft Entra ID. Daarna roep je Connect-PnPOnline aan met je sitelink en de client-ID van die app, plus één aanmeldmethode: interactief, apparaatcode, certificaat, beheerde identiteit of verouderde referenties. Deze gids is bedoeld voor SharePoint-beheerders die scripts handmatig of volgens planning uitvoeren. Hij legt uit wat elke optie doet, wanneer je hem gebruikt en welke fouten een verbinding laten mislukken. Ook laat hij zien hoe je per taak één optie kiest, zodat een script niet meer toegang heeft dan de taak vereist.
Belangrijkste punten
- Sinds 9 september 2024 heeft Connect-PnPOnline een -ClientId nodig. Elke beheerder moet daarom eerst een app registreren in Microsoft Entra ID waarmee de module kan aanmelden.
- Interactief aanmelden is de juiste keuze voor een persoon achter het toetsenbord, omdat het meervoudige verificatie ondersteunt en geen opgeslagen geheim nodig heeft.
- Taken zonder gebruiker gebruiken het best aanmelden met een certificaat of een beheerde identiteit, niet een getypt wachtwoord en niet een clientgeheim dat in een script is opgeslagen.
- De verouderde methode met een clientgeheim werkt alleen voor SharePoint-cmdlets. Elke opdracht die Microsoft Graph aanroept, mislukt daarom met deze methode.
- Registreer de app alleen met de gedelegeerde machtigingen die je nodig hebt, want de standaardregistratie vraagt brede rechten zoals AllSites.FullControl.
Aan de slag: waarom elke verbinding je eigen app nodig heeft
PnP PowerShell is een module die door de community wordt onderhouden. Hij heeft zelf geen bijzondere rechten. Elke aanmelding verloopt via een app-registratie in Microsoft Entra, en die app bepaalt wat het script mag doen.
In de referentie van Connect-PnPOnline staat dat je vanaf 9 september 2024 de parameter -ClientId moet opgeven. Er staat ook dat je eerst een eigen app moet registreren. In plaats van de ID elke keer in te typen, kun je de omgevingsvariabele ENTRAID_APP_ID of ENTRAID_CLIENT_ID instellen.
Dit heeft oudere scripts veranderd. Als een script uit 2023 alleen Connect-PnPOnline -Url ... -Interactive aanroept, mislukt het nu of vraagt het om een ontbrekende client-ID. De oplossing zit niet in de logica van het script. Je hebt een app en een ID nodig.
Twee andere waarden komen in elk voorbeeld terug:
-Urlis het adres van de site waarop je wilt werken, zoalshttps://contoso.sharepoint.com/sites/finance. Voor de meeste methoden is deze waarde verplicht.-Tenantis de naam van de tenant, zoalscontoso.onmicrosoft.com. In de referentie staat dat deze verplicht is voor de methoden met certificaat en thumbprint. Voor interactief aanmelden en apparaatcode is hij optioneel.
Als een opdracht het SharePoint-beheercentrum nodig heeft, kun je -TenantAdminUrl opgeven. Laat je deze weg, dan gaan de cmdlets uit van de vorm https://[tenantname]-admin.sharepoint.com, waar dat van toepassing is.
Stap 1: voltooi de app-registratie in Microsoft Entra
Deze stap voor het aan de slag gaan veronderstelt dat de PnP.PowerShell-module al op je machine is geïnstalleerd. PnP biedt een hulpfunctie voor de eerste installatie. De cmdletpagina voor Register-PnPEntraIDAppForInteractiveLogin toont de kortste vorm:
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com
Er opent een browservenster zodat je kunt aanmelden, en de cmdlet maakt de app aan. Daarnaast toont hij de applicatie-ID die je gebruikt als -ClientId. Voeg -DeviceLogin toe als je geen browser kunt openen op de machine. Volgens de pagina schakelt dit over naar een apparaatloginflow die multifactorauthenticatie ondersteunt.
Let op de machtigingen. Bij het eenvoudige voorbeeld vraagt de app de volgende gedelegeerde machtigingen aan ter goedkeuring: AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All en TermStore.ReadWrite.All. Het tweede voorbeeld op dezelfde pagina beperkt dit met -GraphDelegatePermissions "Group.Read.All" en -SharePointDelegatePermissions "AllSites.FullControl".
Dat is belangrijk voor het principe van minimale rechten. Een rapportscript dat alleen leest, heeft geen schrijfrechten op gebruikers en groepen nodig. Bepaal wat je scripts nodig hebben, en vraag alleen dat aan.
Houd per app-registratie bij: de naam, de client-ID, de eigenaar en de machtigingen die de app heeft. Controleer de app-registratie één keer per jaar, en verwijder hem zodra geen enkel script hem nog gebruikt.
Er zijn twee beperkingen om te kennen. De referentiepagina vermeldt niet welke Entra-rol je nodig hebt om een app te registreren, dus vraag dit na bij je identiteitsbeheerder voordat je begint. En de parameter -SignInAudience bepaalt welke accounttypen de app ondersteunt, dus controleer of die overeenkomt met je tenant.
Verbinden met SharePoint Online met PnP PowerShell: de vijf opties
Alle vijf voorbeelden gebruiken de referentie van Connect-PnPOnline als bron. Vervang de waarden tussen punthaken.
Interactief aanmelden
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>
Dit is de standaardkeuze voor een persoon. De referentie zegt dat het is ontworpen om multifactorauthenticatie te ondersteunen. Voeg -ForceAuthentication toe om opgeslagen authenticatie te wissen en je aan te melden met een ander account. Gebruik dit wanneer je schakelt tussen een test- en een productietenant.
Apparaatlogin
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>
Er opent een browser en de code wordt naar je klembord gekopieerd. Kies deze optie wanneer de shell draait in een externe sessie waarin een interactief venster niet goed werkt.
Certificaataanmelding (alleen app)
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>
Er meldt geen persoon zich aan. De app handelt zelfstandig, met de toepassingsmachtigingen die je hem hebt gegeven. Je kunt -CertificatePath gebruiken met -CertificatePassword, een -CertificateBase64Encoded-waarde, of een -Thumbprint. De thumbprint-methode vereist dat het certificaat in de Windows-certificaatopslag staat. Dit is de standaardkeuze voor onbeheerde scripts op een server.
Beheerde identiteit
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity
Volgens de referentie werkt dit alleen in omgevingen die beheerde identiteiten ondersteunen, zoals Azure Functions, Automation-runbooks en Cloud Shell. Je bewaart helemaal geen geheim. Voor een door de gebruiker toegewezen identiteit voeg je één van -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId of -UserAssignedManagedIdentityAzureResourceId toe. De parameter -Url is bij deze methode optioneel.
Inloggegevens en clientgeheimen
Twee oudere methoden bestaan nog, en bij beide gelden waarschuwingen.
-Credentialsneemt een PSCredential, bijvoorbeeld(Get-Credential), of de naam van een Generic Credential in Windows-referentiebeheer. De referentie noemt ondersteuning voor multifactorauthenticatie bij interactief en apparaatlogin, maar doet die claim hier niet. Beschouw dit als optie voor accounts zonder prompt, en test voordat je erop vertrouwt.-ClientSecretmet-ClientIdis de verouderde ACS-methode. In de referentie staat dat je hiermee alleen "cmdlets gebruiken die verbinding maken met SharePoint Online". Cmdlets die Microsoft Graph gebruiken, mislukken.
Vermijd beide voor alles wat nieuw is. Een wachtwoord in een script is een risico, en een clientgeheim verloopt zonder waarschuwing.
Voorbeeld: een aanmeldoptie kiezen voor vier taken
De getallen en namen hieronder zijn verzonnen om het voorbeeld te illustreren.
Een beheerteam bij een fictief bedrijf voert vier taken uit. Ze willen één app per risiconiveau, niet één app voor alles.
- Ad-hoccontroles door een beheerder op een laptop. Gebruik
-Interactivemet een app die beperkte gedelegeerde machtigingen heeft. De beheerder meldt zich aan met MFA. Er wordt niets opgeslagen. - Een eenmalige opschoonactie op een externe jumpserver. Gebruik
-DeviceLogin. De beheerder voltooit de aanmelding op een telefoon of laptop en daarna start de taak. - Een nachtelijke inventarisatie op een Windows-server. Gebruik een certificaat met
-Thumbprint. De app heeft alleen-lezen toepassingsmachtigingen. Het certificaat is 12 maanden geldig en het team zet de vernieuwingsdatum in een gedeelde agenda. - Een wekelijkse taak in een Automation-runbook. Gebruik
-ManagedIdentity. Er is geen certificaat of geheim dat je moet roteren.
Het resultaat: alleen taak 1 en taak 2 zijn afhankelijk van een persoon. Taken 3 en 4 draaien zonder dat iemand aanwezig is, en geen van beide slaat een wachtwoord op. Als de server van taak 3 wordt gestolen, trekt het team één certificaat in. Ze hoeven geen beheerderswachtwoord te resetten.
Welke optie je ook kiest, bewaar de site-URL in een variabele zoals $siteUrl. Zo kan één PowerShell-script elke site in een lijst van sites doorlopen, de benodigde gegevens per SharePoint-site ophalen en een rapport uploaden. Test het script eerst op één sitecollectie voordat je het uitrolt over je Microsoft 365-tenant.
Veelgemaakte fouten
- Vergeten van
-ClientId. De verbinding mislukt of vraagt om de ID. Sla de ID op in de omgevingsvariabeleENTRAID_APP_IDop computers waarop je vaak scripts uitvoert. - Eén almachtige app voor alles gebruiken. De standaardregistratie vraagt om AllSites.FullControl en schrijfrechten voor gebruikers en groepen. Registreer een tweede, alleen-lezen app voor rapportages.
- Een clientgeheim gebruiken met op Graph gebaseerde cmdlets. De verouderde methode werkt alleen voor SharePoint-cmdlets. Als een opdracht Graph aanroept, mislukt die, en de foutmelding kan verwarrend zijn.
- Een wachtwoord of geheim in het scriptbestand zetten. Iedereen met leestoegang tot het bestand heeft dan de inloggegevens. Gebruik een certificaatopslag of een beheerde identiteit.
- De aanmelding niet testen in de uiteindelijke omgeving. Een script dat op je laptop werkt met
-Interactive, kan mislukken op een server zonder browser. Test met de methode die de taak daadwerkelijk gaat gebruiken. - Aangemeld blijven bij de verkeerde tenant. Gebruik
-ForceAuthenticationwanneer je van account wisselt, en toon de verbindingsgegevens aan het begin van elk script.
Hoe software kan helpen
Begin met wat je al hebt. De PnP-module en de Microsoft Graph PowerShell SDK dekken het grootste deel van het beheerscripting. Azure Automation voert scripts volgens een schema uit met een beheerde identiteit, en het SharePoint-beheercentrum toont sites en instellingen zonder code. Voor geheimen is een certificaatopslag of een key vault veiliger dan een scriptbestand.
Voeg daar rapportage aan toe. Een script dat correct verbinding maakt, is alleen de eerste stap. Teams hebben ook een duidelijk logboek nodig van wat elk script heeft gewijzigd en welke app-identiteit het gebruikte, zodat de volgende beheerder het kan volgen. Bewaar dat logboek op een plek die iedereen kan lezen, zoals een gedeelde lijst of een ticketsysteem.
Volgende stap
Registreer vandaag nog één app met de kleinste set gedelegeerde machtigingen die je scripts nodig hebben. Test daarna of je met -Interactive verbinding kunt maken met SharePoint Online via PnP PowerShell, en noteer welke aanmeldoptie elk van je geplande taken gaat gebruiken.