Connettersi a Sicurezza e conformità PowerShell

Questo articolo contiene istruzioni su come connettersi a PowerShell per la sicurezza & la conformità usando il modulo PowerShell Exchange Online con o senza autenticazione a più fattori (MFA).

Il modulo Exchange Online PowerShell usa l'autenticazione moderna per la connessione a PowerShell e Exchange Online PowerShell per la sicurezza & la conformità. Per altre informazioni sul modulo PowerShell di Exchange Online, vedere Informazioni sul modulo PowerShell di Exchange Online.

Per connettersi a Sicurezza & Conformità di PowerShell per l'automazione, vedere Autenticazione solo dell'app per gli script automatici.

Che cosa è necessario sapere prima di iniziare?

• I requisiti per l'installazione e l'uso del modulo sono descritti in Prerequisiti per il modulo PowerShell di Exchange Online e Sistemi operativi supportati per il modulo PowerShell di Exchange Online.

• Dopo la connessione, il controllo di accesso in base ai ruoli controlla i cmdlet e i parametri a cui si ha o non si ha accesso. Per altre informazioni, vedere Autorizzazioni nel portale di Microsoft Defender e Autorizzazioni nel portale di Microsoft Purview.

Passaggio 1: Caricare il modulo PowerShell di Exchange Online

Nota

Se il modulo è già installato, in genere è possibile ignorare questo passaggio ed eseguire Connect-IPPSSession senza prima caricare manualmente il modulo.

Dopo aver installato il modulo, aprire una finestra di PowerShell e caricare il modulo eseguendo il comando seguente:

Import-Module ExchangeOnlineManagement

Passaggio 2: Connettersi e autenticarsi

Nota

• I comandi di connessione probabilmente non riescono se il percorso del profilo dell'account utilizzato per la connessione contiene caratteri speciali di PowerShell, $ad esempio . La soluzione alternativa consiste nel connettersi usando un account diverso che non contenga caratteri speciali nel percorso del profilo.

• Se si prevede di eseguire i cmdlet di eDiscovery (*-ComplianceSearch o New-ComplianceSearchAction), la connessione deve soddisfare i requisiti seguenti:

  • Versione 3.9.0 (agosto 2025) o successiva del modulo PowerShell di Exchange Online.

  • Il comando connect deve includere l'opzione EnableSearchOnlySession .

    Se la connessione PowerShell per la sicurezza & la conformità non soddisfa questi requisiti, viene visualizzato l'errore seguente quando si tenta di eseguire i cmdlet di eDiscovery:

    Please close the current PowerShell session and open a new session using Connect-IPPSSession with the -EnableSearchOnlySession flag. This requires using ExchangeOnlineManagement v3.9.0 or higher.

Il comando da eseguire utilizza la sintassi seguente:

Connect-IPPSSession -UserPrincipalName <UPN> [-ConnectionUri <URL>] [-AzureADAuthorizationEndpointUri <URL>] [-DelegatedOrganization <String>] [-PSSessionOption $ProxyOptions] [-EnableSearchOnlySession]

Per informazioni dettagliate su sintassi e parametri, vedere Connect-ExchangeOnlineIPPSSession .

• <UPN> è l'account nel formato del nome dell'entità utente, navin@contoso.onmicrosoft.comad esempio .

• I valori di ConnectionUri e AzureADAuthorizationEndpointUri necessari dipendono dalla natura dell'organizzazione di Microsoft 365. I valori comuni sono descritti nell'elenco seguente:

  • Microsoft 365 o Microsoft 365 GCC:
    • ConnectionUri: nessuno. Il valore https://ps.compliance.protection.outlook.com/powershell-liveid/ richiesto è anche il valore predefinito, quindi non è necessario usare il parametro ConnectionUri negli ambienti Microsoft 365 o Microsoft 365 GCC.
    • AzureADAuthorizationEndpointUri: Nessuno. Il valore https://login.microsoftonline.com/organizationsobbligatorio, ma è anche il valore predefinito, quindi non è necessario usare il parametro AzureADAuthorizationEndpointUri negli ambienti GCC di Microsoft 365 o Microsoft 365.
  • Microsoft 365 GCC High:
    • ConnectionUri: https://ps.compliance.protection.office365.us/powershell-liveid/
    • AzureADAuthorizationEndpointUri: https://login.microsoftonline.us/organizations^*
  • Microsoft 365 DoD:
    • ConnectionUri: https://l5.ps.compliance.protection.office365.us/powershell-liveid/
    • AzureADAuthorizationEndpointUri: https://login.microsoftonline.us/organizations^*
  • Office 365 gestito da 21Vianet:
    • ConnectionUri: https://ps.compliance.protection.partner.outlook.cn/powershell-liveid
    • AzureADAuthorizationEndpointUri: https://login.chinacloudapi.cn/organizations^*

  ^* Il valore AzureADAuthorizationEndpointUri che termina con /organizations consente solo gli account aziendali o dell'istituto di istruzione. Il valore URI precedente che termina con /common funziona ancora, ma potrebbe essere richiesto di scegliere tra un account personale e un account aziendale o dell'istituto di istruzione. È consigliabile usare il /organizations valore URI negli scenari aziendali in cui gli account consumer devono essere esclusi.

• Se si è dietro un server proxy, è possibile usare il parametro PSSessionOption nel comando di connessione. Per prima cosa, esegui questo comando: $ProxyOptions = New-PSSessionOption -ProxyAccessType <Value>, dove <Value> è IEConfig, WinHttpConfig, o AutoDetect. Usare quindi il valore $ProxyOptions per il parametro PSSessionOption . Per altre informazioni, vedere New-PSSessionOption.

• A seconda della natura dell'organizzazione, è possibile omettere il parametro UserPrincipalName nel passaggio successivo. Al contrario, immettere il nome utente e la password o selezionare le credenziali archiviate dopo aver eseguito il comando Connect-IPPSSession. Se questa operazione non funziona, è necessario usare il parametro UserPrincipalName.

• Se non si usa l'autenticazione a più fattori (MFA), dovrebbe essere possibile usare il parametro Credential anziché il parametro UserPrincipalName. Per prima cosa, eseguire il comando $Credential = Get-Credential, immettere nome utente e password, quindi usare il nome variabile per il parametro Credential (-Credential $Credential). Se questa operazione non funziona, è necessario usare il parametro UserPrincipalName.

Connettersi a PowerShell per la sicurezza & la conformità con una richiesta di accesso interattiva

1. Gli esempi seguenti funzionano in Windows PowerShell 5.1 e PowerShell 7 per gli account con o senza MFA:

   • Questo esempio consente di connettersi a PowerShell in Sicurezza e conformità in un'organizzazione di Microsoft 365 o Microsoft 365 GCC:

     Connect-IPPSSession -UserPrincipalName navin@contoso.onmicrosoft.com
     

   • Questo esempio consente di connettersi a PowerShell in Sicurezza e conformità in un'organizzazione di Microsoft GCC High:

     Connect-IPPSSession -UserPrincipalName chris@govt.us -ConnectionUri https://ps.compliance.protection.office365.us/powershell-liveid/ -AzureADAuthorizationEndpointUri https://login.microsoftonline.us/organizations
     

   • Questo esempio consente di connettersi a PowerShell in Sicurezza e conformità in un'organizzazione di Microsoft 365 DoD:

     Connect-IPPSSession -UserPrincipalName michelle@govt.mil -ConnectionUri https://l5.ps.compliance.protection.office365.us/powershell-liveid/ -AzureADAuthorizationEndpointUri https://login.microsoftonline.us/organizations
     

   • Questo esempio si connette a Sicurezza e conformità PowerShell in un'organizzazione di Office 365 gestita da 21Vianet:

     Connect-IPPSSession -UserPrincipalName li@fabrikam.cn -ConnectionUri https://ps.compliance.protection.partner.outlook.cn/powershell-liveid -AzureADAuthorizationEndpointUri https://login.chinacloudapi.cn/organizations
     

2. Nella finestra di accesso visualizzata immettere la password e quindi selezionare Accedi.

   

   Nota

   In PowerShell 7, l'accesso Single Sign-On (SSO) basato su browser viene usato per impostazione predefinita, quindi la richiesta di accesso viene aperta nel Web browser predefinito anziché in una finestra di dialogo autonoma.

3. Solo autenticazione a più fattori: viene generato e recapitato un codice di verifica in base all'opzione di risposta configurata per l'account (ad esempio, un SMS o l'app Microsoft Authenticator sul dispositivo).

   Nella finestra di verifica visualizzata immettere il codice di verifica e quindi selezionare Verifica.

   

Connettersi a PowerShell per la sicurezza & la conformità senza una richiesta di accesso (script automatici)

Per istruzioni complete, vedere Autenticazione solo app per script automatici in Exchange Online PowerShell e Sicurezza & Conformità PowerShell.

Connettersi a PowerShell per la sicurezza & la conformità nelle organizzazioni dei clienti

Le procedure descritte in questa sezione richiedono la versione 3.0.0 o successiva del modulo.

In PowerShell per la sicurezza & la conformità è necessario usare AzureADAuthorizationEndpointUri con il parametro DelegatedOrganization .

Per ulteriori informazioni sui partner e sulle organizzazioni clienti, vedere gli articoli seguenti:

• Che cos'è il programma Cloud Solution Provider (CSP)?
• Introduzione ai privilegi granulari di amministratore delegato (GDAP)

Questo esempio si connette alle organizzazioni dei clienti negli scenari seguenti:

• Connettersi a un'organizzazione cliente utilizzando un account CSP.

• Connettersi a un'organizzazione del cliente usando un GDAP.

• Connettersi a un'organizzazione cliente come guest.

  Connect-IPPSSession -UserPrincipalName navin@contoso.onmicrosoft.com -DelegatedOrganization adatum.onmicrosoft.com -AzureADAuthorizationEndpointUri https://login.microsoftonline.com/adatum.onmicrosoft.com
  

Passaggio 3: disconnettiti quando hai finito

Al termine, assicurarsi di disconnettere la sessione. Se chiudi la finestra di PowerShell senza disconnettere la sessione, potresti usare tutte le sessioni disponibili ed è necessario attendere la scadenza delle sessioni. Per disconnettere la sessione, eseguire il comando seguente:

Disconnect-ExchangeOnline

Per disconnettersi automaticamente senza una richiesta di conferma, esegui il comando seguente:

Disconnect-ExchangeOnline -Confirm:$false

Nota

È probabile che il comando disconnect abbia esito negativo se il percorso del profilo dell'account utilizzato per la connessione contiene caratteri speciali di PowerShell, $ad esempio . La soluzione alternativa consiste nel connettersi usando un account diverso che non contenga caratteri speciali nel percorso del profilo.

Come fai a sapere se ti sei connesso correttamente?

I cmdlet di Sicurezza e conformità PowerShell vengono importati nella tua sessione Windows PowerShell locale come mostrato da una barra di avanzamento. Se non vengono visualizzati errori, la connessione è stata eseguita correttamente. Un breve test consiste nell'eseguire un cmdlet di Sicurezza e conformità Poweshell (ad esempio, Get-RetentionCompliancePolicy) e vedere i risultati.

Se non vengono visualizzati errori, controllare i requisiti seguenti:

• Un problema comune è rappresentato da una password errata. Eseguire di nuovo i tre passaggi e prestare particolare attenzione al nome utente e alla password usati.

• L'account usato per la connessione deve essere abilitato per PowerShell. Per altre informazioni, vedere Abilitare o disabilitare l’accesso a PowerShell di Exchange Online..

• Il traffico sulla porta TCP 80 deve essere aperto tra il computer locale e Microsoft 365. È probabile che sia aperto, ma è bene verificare se l'organizzazione prevede criteri restrittivi relativi all'accesso a Internet.

• Le connessioni basate su REST a PowerShell per la sicurezza & la conformità richiedono il modulo PowerShellGet. Per dipendenza, il modulo PowerShellGet richiede il modulo PackageManagement. Se tenti di connetterti senza aver installato entrambi i moduli, vengono visualizzati degli errori. Ad esempio, potrebbe essere visualizzato l'errore seguente:

  Il termine "Update-ModuleManifest" non è riconosciuto come nome di un cmdlet, una funzione, un file di script o un programma eseguibile. Controllare l'ortografia del nome oppure, se è stato incluso un percorso, verificare che questo sia corretto e riprovare.

  Per altre informazioni sui requisiti del modulo PowerShellGet e PackageManagement, vedere PowerShellGet per connessioni basate su REST in Windows.

• Potrebbe non essere possibile connettersi se l'indirizzo IP del client cambia durante la richiesta di connessione. L'errore si verifica se l'organizzazione usa un pool SNAT (Source Network Address Translation) con più indirizzi IP. L'errore di connessione ha questo aspetto:

  La richiesta per la shell remota di Windows con ID> ShellId <non è riuscita perché la shell non è stata trovata sul server. Le possibili cause sono: il valore di ShellId specificato non è corretto oppure la shell non esiste più nel server. Fornire la ShellId corretta o creare una nuova shell e ripetere l'operazione.

  Per risolvere il problema, eseguire una delle operazioni seguenti:

  • Usare un pool SNAT contenente un singolo indirizzo IP.
  • Forzare l'uso di un indirizzo IP specifico per le connessioni all'endpoint di PowerShell per la sicurezza & la conformità.