Connettersi a Sicurezza e conformità PowerShell

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

Il modulo PowerShell di Exchange Online usa l'autenticazione moderna per la connessione a tutti gli ambienti PowerShell correlati a Exchange in Microsoft 365: PowerShell di Exchange Online, PowerShell per la sicurezza & conformità e PowerShell autonomo di Exchange Online Protection (EOP). Per altre informazioni sul modulo PowerShell di Exchange Online, vedere Informazioni sul modulo PowerShell di Exchange Online.

Per connettersi a Security & Compliance PowerShell per l'automazione, vedere Autenticazione solo app per script automatici.

Che cosa è necessario sapere prima di iniziare?

• I requisiti per l'installazione e l'uso del modulo sono descritti in Installare e gestire il modulo PowerShell di Exchange Online.

  Nota

  Le connessioni Remote PowerShell sono deprecate in PowerShell sicurezza & conformità. Per altre informazioni, vedere Deprecation of Remote PowerShell (RPS) Protocol in Security & Compliance PowerShell.For more information, see Deprecation of Remote PowerShell (RPS) Protocol in Security & Compliance PowerShell.

  Le connessioni API REST nel modulo PowerShell V3 di Exchange Online richiedono i moduli PowerShellGet e PackageManagement. Per altre informazioni, vedere PowerShellGet per le connessioni basate su REST in Windows.

• In seguito alla connessione, i cmdlet e i parametri per cui si dispone o meno dell'accesso vengono controllati dal controllo degli accessi in base al ruolo. Per altre informazioni, vedere Autorizzazioni nel portale di Microsoft Defender e Autorizzazioni nel portale di conformità di Microsoft Purview.

Passaggio 1: Caricare il modulo PowerShell di Exchange Online

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 autenticare

Il comando da eseguire utilizza la sintassi seguente:

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

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 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/ obbligatorio è anche il valore predefinito, quindi non è necessario usare il parametro ConnectionUri negli ambienti GCC di Microsoft 365 o Microsoft 365.
    • AzureADAuthorizationEndpointUri: nessuno. Il valore https://login.microsoftonline.com/common obbligatorio è 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/common
  • Microsoft 365 DoD:
    • ConnectionUri: https://l5.ps.compliance.protection.office365.us/powershell-liveid/
    • AzureADAuthorizationEndpointUri: https://login.microsoftonline.us/common
  • Office 365 gestito da 21Vianet:
    • ConnectionUri: https://ps.compliance.protection.partner.outlook.cn/powershell-liveid
    • AzureADAuthorizationEndpointUri: https://login.chinacloudapi.cn/common

• Se si è dietro un server proxy, è possibile usare il parametro PSSessionOption nel comando di connessione. Eseguire prima di tutto questo comando: $ProxyOptions = New-PSSessionOption -ProxyAccessType <Value>, dove <Value> è IEConfig, WinHttpConfigo 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 Security & Compliance PowerShell con un prompt di accesso interattivo

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/common
     

   • 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/common
     

   • 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/common
     

2. Nella finestra di accesso che viene visualizzata, immettere la password, quindi fare clic su Accedi.

   

   Nota

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

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

   Nella finestra di verifica che viene visualizzata, immettere il codice di verifica, quindi fare clic su Verifica.

   

Connettersi a Security & Compliance PowerShell senza una richiesta di accesso (script automatici)

Per istruzioni complete, vedere Autenticazione solo app per script automatici in PowerShell di Exchange Online e PowerShell per la sicurezza & conformità.

Connettersi a Security & Compliance PowerShell nelle organizzazioni dei clienti

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

In Security & Compliance PowerShell è necessario usare AzureADAuthorizationEndpointUri con il parametro DelegatedOrganization .

Per altre informazioni sui partner e le organizzazioni dei clienti, vedere gli argomenti seguenti:

• Che cos'è il programma Cloud Solution Provider (CSP).What is the Cloud Solution Provider (CSP)?.
• Introduzione ai privilegi di amministratore delegato granulare (GDAP)

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

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

• Connettersi a un'organizzazione cliente usando un GDAP.

• Connettersi a un'organizzazione cliente come utente guest.

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

Passaggio 3: Disconnetti al termine

Assicurarsi di disconnettere la sessione al termine. Se si chiude la finestra di PowerShell senza disconnettere la sessione, è possibile usare tutte le sessioni disponibili ed è necessario attendere la scadenza delle sessioni. Per disconnettere la sessione, eseguire il comando seguente:

Disconnect-ExchangeOnline

Per disconnettersi in modo invisibile all'utente senza un prompt di conferma, eseguire il comando seguente:

Disconnect-ExchangeOnline -Confirm:$false

Come si fa a sapere che la connessione è stata eseguita 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 si ricevono 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 connettersi 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 Security & Compliance PowerShell richiedono il modulo PowerShellGet e, per dipendenza, il modulo PackageManagement, quindi si riceveranno errori se si tenta di connettersi senza installarli. Ad esempio, potrebbe essere visualizzato l'errore seguente:

  Il termine "Update-ModuleManifest" non è riconosciuto come nome di un cmdlet, di una funzione, di un file di script o di un programma operabile. 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 le connessioni basate su REST in Windows.

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

  La richiesta per Windows Remote Shell con ID> ShellId <non è riuscita perché la shell non è stata trovata nel 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, usare un pool di SNAT che contiene un singolo indirizzo IP o forzare l'uso di un indirizzo IP specifico per le connessioni all'endpoint di PowerShell di sicurezza & conformità.