Connessione a SharePoint Online con PnP PowerShell: opzioni di accesso
By Mirko Peters · · Updated
Connessione a SharePoint Online con PnP PowerShell: registra una tua app in Entra e scegli, per ogni attività, l'accesso interattivo, da dispositivo, con certificato o con identità gestita.
Automatically translated with AI from the original post. Read the English original
Per connetterti oggi a SharePoint Online con PnP PowerShell, registri una volta la tua app in Microsoft Entra ID. Poi chiami Connect-PnPOnline con l'URL del sito e l'ID client di quell'app, più un metodo di accesso: interattivo, login da dispositivo, certificato, identità gestita o credenziali legacy. Questa guida è pensata per gli amministratori di SharePoint che eseguono script manualmente o in modo pianificato. Spiega che cosa fa ciascuna opzione, quando usarla e quali errori interrompono la connessione. Mostra anche come scegliere un'opzione per ogni processo, così uno script non ha più accessi di quelli che il suo compito richiede.
Punti chiave
- Dal 9 settembre 2024 Connect-PnPOnline richiede un -ClientId, quindi ogni amministratore deve prima registrare in Microsoft Entra ID un'app con cui il modulo possa accedere.
- L'accesso interattivo è la scelta giusta per una persona davanti alla tastiera, perché supporta l'autenticazione a più fattori e non richiede alcun segreto memorizzato.
- I processi senza presidio devono usare l'accesso con certificato o un'identità gestita, non una password digitata e non un segreto client memorizzato in uno script.
- Il metodo legacy con segreto client funziona solo per i cmdlet di SharePoint, quindi qualsiasi comando che chiama Microsoft Graph con questo metodo non riuscirà.
- Registra l'app solo con le autorizzazioni delegate di cui hai bisogno, perché la registrazione predefinita richiede diritti ampi come AllSites.FullControl.
Per iniziare: perché ogni connessione richiede una tua app
PnP PowerShell è un modulo mantenuto dalla community. Non possiede diritti speciali. Ogni accesso passa attraverso una registrazione app in Microsoft Entra, e quell'app stabilisce che cosa può fare lo script.
La documentazione di riferimento di Connect-PnPOnline indica che dal 9 settembre 2024 devi fornire il parametro -ClientId. Specifica inoltre che devi prima registrare una tua app. Puoi impostare la variabile d'ambiente ENTRAID_APP_ID o ENTRAID_CLIENT_ID invece di digitare l'ID ogni volta.
Questo cambia gli script più vecchi. Se uno script del 2023 chiama Connect-PnPOnline -Url ... -Interactive e nient'altro, ora fallirà oppure chiederà un ID client mancante. La soluzione non sta nella logica dello script: ti servono un'app e un ID.
Altri due valori compaiono in ogni esempio:
-Urlè l'indirizzo del sito su cui vuoi lavorare, ad esempiohttps://contoso.sharepoint.com/sites/finance. È obbligatorio per la maggior parte dei metodi.-Tenantè il nome del tenant, ad esempiocontoso.onmicrosoft.com. La documentazione di riferimento lo indica come obbligatorio per i metodi con certificato e impronta digitale. È facoltativo per l'accesso interattivo e il login da dispositivo.
Se un comando richiede l'interfaccia di amministrazione di SharePoint, puoi passare -TenantAdminUrl. Se lo ometti, i cmdlet assumono la forma https://[tenantname]-admin.sharepoint.com dove previsto.
Passaggio 1: completa la registrazione dell'app in Microsoft Entra
Questo passaggio di avvio presuppone che il modulo PnP.PowerShell sia già installato sul tuo computer. PnP offre un helper per la configurazione iniziale. La pagina dei cmdlet per Register-PnPEntraIDAppForInteractiveLogin mostra la forma più breve:
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com
Si apre una finestra del browser per l'accesso e il cmdlet crea l'app. Stampa anche l'ID applicazione che userai come -ClientId. Aggiungi -DeviceLogin se sul computer non puoi aprire un browser. La pagina indica che questa opzione passa a un flusso di accesso tramite dispositivo che supporta l'autenticazione a più fattori.
Fai attenzione alle autorizzazioni. Con l'esempio base, l'app richiede per il consenso queste autorizzazioni delegate: AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All e TermStore.ReadWrite.All. Il secondo esempio della stessa pagina le riduce con -GraphDelegatePermissions "Group.Read.All" e -SharePointDelegatePermissions "AllSites.FullControl".
Questo conta per il principio del privilegio minimo. Uno script di report che si limita a leggere non ha bisogno di permessi di scrittura su utenti e gruppi. Decidi di cosa hanno bisogno i tuoi script e chiedi solo quello.
Tieni traccia di ogni registrazione dell'app: nome, ID client, proprietario e autorizzazioni che possiede. Verifica la registrazione dell'app una volta all'anno ed eliminala quando nessuno script la usa più.
Due limiti da conoscere. La pagina di riferimento non indica quale ruolo di Entra serve per registrare un'app, quindi chiedi al tuo amministratore dell'identità prima di iniziare. Inoltre il parametro -SignInAudience controlla quali tipi di account supporta l'app, quindi verifica che corrisponda al tuo tenant.
Come connettersi a SharePoint Online con PnP PowerShell: le cinque opzioni
Tutti e cinque gli esempi usano come riferimento la documentazione di Connect-PnPOnline. Sostituisci i valori tra parentesi angolari.
Accesso interattivo
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>
Questa è la scelta predefinita per una persona. La documentazione afferma che è progettata per supportare l'autenticazione a più fattori. Aggiungi -ForceAuthentication per cancellare l'autenticazione memorizzata e accedere con un altro account. Usalo quando passi da un tenant di test a uno di produzione.
Accesso tramite dispositivo
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>
Si apre un browser e il codice viene copiato negli appunti. Scegli questa opzione quando la shell viene eseguita in una sessione remota in cui una finestra interattiva non funziona bene.
Accesso con certificato (solo app)
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>
Nessuna persona accede. L'app agisce autonomamente, con le autorizzazioni applicative che le hai concesso. Puoi passare -CertificatePath con -CertificatePassword, un valore -CertificateBase64Encoded oppure un -Thumbprint. Il metodo con thumbprint richiede che il certificato sia nell'archivio certificati di Windows. È la scelta standard per gli script non presidiati su un server.
Identità gestita
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity
La documentazione indica che questo metodo funziona solo in ambienti che supportano le identità gestite, come Azure Functions, i runbook di Automation e Cloud Shell. Non memorizzi alcun segreto. Per un'identità assegnata dall'utente, aggiungi uno tra -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId o -UserAssignedManagedIdentityAzureResourceId. Con questo metodo il parametro -Url è facoltativo.
Credenziali e client secret
Restano due metodi meno recenti, e per entrambi ci sono avvertenze.
-Credentialsaccetta un PSCredential, ad esempio(Get-Credential), oppure il nome di una credenziale generica in Gestione credenziali di Windows. La documentazione elenca il supporto dell'autenticazione a più fattori per l'accesso interattivo e tramite dispositivo, ma qui non lo afferma. Consideralo un'opzione per gli account senza richiesta di accesso e verifica prima di farci affidamento.-ClientSecretcon-ClientIdè il metodo ACS legacy. La documentazione indica che, con questo metodo, "solo i cmdlet che si connettono a SharePoint Online funzionano". I cmdlet che usano Microsoft Graph non funzionano.
Evita entrambi per qualsiasi nuovo progetto. Una password in uno script è un rischio, e un client secret scade senza preavviso.
Esempio: scegliere un'opzione di accesso per quattro attività
I numeri e i nomi qui sotto sono inventati a scopo illustrativo.
Il team di amministrazione di un'azienda fittizia gestisce quattro attività. Vogliono un'app per ogni livello di rischio, non un'unica app per tutto.
- Verifiche ad hoc da parte di un amministratore dal proprio portatile. Usa
-Interactivecon un'app che ha autorizzazioni delegate limitate. L'amministratore accede con MFA. Non viene memorizzato nulla. - Un'operazione di pulizia una tantum su un jump server remoto. Usa
-DeviceLogin. L'amministratore completa l'accesso da un telefono o da un portatile e l'esecuzione parte. - Un inventario notturno su un server Windows. Usa un certificato con
-Thumbprint. L'app ha autorizzazioni applicative di sola lettura. Il certificato è valido per 12 mesi e il team inserisce la data di rinnovo in un calendario condiviso. - Un'attività settimanale in un runbook di Automation. Usa
-ManagedIdentity. Non ci sono certificati o segreti da ruotare.
Il risultato: solo l'attività 1 e l'attività 2 dipendono da una persona. Le attività 3 e 4 vengono eseguite senza che nessuno sia presente, e nessuna delle due memorizza una password. Se il server dell'attività 3 viene rubato, il team revoca un solo certificato. Non devono reimpostare la password di un amministratore.
Qualunque opzione tu scelga, conserva l'URL del sito in una variabile come $siteUrl, così uno script PowerShell può scorrere ciascun sito di un elenco di siti, recuperare da ciascun sito SharePoint ciò che serve e caricare un report. Prova lo script su una singola raccolta siti prima di eseguirlo su tutto il tuo tenant di Microsoft 365.
Errori comuni
- Dimenticare
-ClientId. La connessione non riesce oppure chiede di inserirlo. Salva l'ID nella variabile di ambienteENTRAID_APP_IDsui computer su cui esegui spesso degli script. - Usare un'unica app onnipotente per tutto. La registrazione predefinita richiede AllSites.FullControl e l'accesso in scrittura a utenti e gruppi. Registra una seconda app, di sola lettura, per i report.
- Usare un client secret con cmdlet basati su Graph. Il metodo legacy funziona solo con i cmdlet di SharePoint. Se un comando chiama Graph, non funzionerà, e il messaggio di errore può essere fuorviante.
- Inserire una password o un secret nel file dello script. Chiunque abbia accesso in lettura al file possiede la credenziale. Usa un archivio certificati o un'identità gestita.
- Non testare l'accesso nell'ambiente finale. Uno script che funziona sul tuo portatile con
-Interactivepuò fallire su un server senza browser. Testa con il metodo che l'attività userà davvero. - Restare connessi al tenant sbagliato. Usa
-ForceAuthenticationquando cambi account e stampa i dettagli della connessione all'inizio di ogni script.
Come può aiutare il software
Parti da ciò che hai già. Il modulo PnP e l'SDK di PowerShell per Microsoft Graph coprono la maggior parte degli script di amministrazione. Azure Automation esegue gli script in base a una pianificazione con un'identità gestita, e l'interfaccia di amministrazione di SharePoint mostra siti e impostazioni senza bisogno di codice. Per i segreti, un archivio certificati o un key vault è più sicuro di un file di script.
Aggiungi poi la reportistica. Uno script che si connette correttamente è solo il primo passo. Anche i team hanno bisogno di un registro chiaro di cosa ha modificato ciascuno script e di quale identità dell'app ha usato, così il prossimo amministratore può seguirne il lavoro. Conserva questo registro in un luogo accessibile a tutti, come un elenco condiviso o un sistema di ticket.
Prossimo passo
Registra oggi stesso un'app con il set più piccolo di autorizzazioni delegate di cui i tuoi script hanno bisogno. Poi verifica di riuscire a connetterti a SharePoint Online con PnP PowerShell usando -Interactive, e annota quale opzione di accesso userà ciascuna delle tue attività pianificate.