Conectar-se ao PowerShell de Segurança e Conformidade

Este artigo contém instruções sobre como se conectar ao PowerShell de Segurança & Conformidade usando o módulo Exchange Online PowerShell com ou sem autenticação multifator (MFA).

O módulo Exchange Online do PowerShell usa autenticação moderna para se conectar ao Exchange Online PowerShell e ao PowerShell de Segurança & Conformidade. Para obter mais informações sobre o módulo do PowerShell do Exchange Online, consulte Sobre o módulo do PowerShell do Exchange Online.

Para se conectar ao PowerShell de Segurança & Conformidade para automação, consulte Autenticação somente do aplicativo para scripts autônomos.

Do que você precisa saber para começar?

• Os requisitos para instalar e usar o módulo são descritos em Pré-requisitos para o módulo do PowerShell do Exchange Online e Sistemas operacionais com suporte para o módulo do PowerShell do Exchange Online.

• Depois que você se conecta, o RBAC (controle de acesso baseado em função) controla os cmdlets e os parâmetros aos quais você tem ou não acesso. Para obter mais informações, consulte Permissões no portal do Microsoft Defender e Permissões no portal do Microsoft Purview.

Etapa 1: Carregar o módulo do PowerShell do Exchange Online

Observação

Se o módulo já estiver instalado, você poderá pular esta etapa e executar Connect-IPPSSession sem carregar manualmente o módulo primeiro.

Após instalar o módulo, abra uma janela do PowerShell e carregue o módulo executando o seguinte comando:

Import-Module ExchangeOnlineManagement

Etapa 2: conectar e autenticar

Observação

• Os comandos de conexão provavelmente falharão se o caminho do perfil da conta usada para conectar contiver caracteres especiais do PowerShell (por exemplo, $). A solução alternativa é conectar-se usando uma conta diferente que não tenha caracteres especiais no caminho do perfil.

• Se você planeja executar cmdlets de Descoberta Eletrônica (*-ComplianceSearch ou New-ComplianceSearchAction), a conexão deve atender aos seguintes requisitos:

  • Versão 3.9.0 (agosto de 2025) ou posterior do módulo do PowerShell do Exchange Online.

  • O comando connect deve incluir a opção EnableSearchOnlySession .

    Se sua conexão do PowerShell de Segurança & Conformidade não atender a esses requisitos, você receberá o seguinte erro ao tentar executar cmdlets de Descoberta Eletrônica:

    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.

O comando que você precisa executar usa a seguinte sintaxe:

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

Para obter informações detalhadas sobre a sintaxe e os parâmetros, confira Connect-IPPSSession.

• UPN é sua conta no formato de nome UPN> (por exemplo, ).<navin@contoso.onmicrosoft.com

• Os valores obrigatórios de ConnectionUri e AzureADAuthorizationEndpointUri dependem da natureza da sua organização do Microsoft 365. Os valores comuns são descritos na lista a seguir:

  • Microsoft 365 ou Microsoft 365 GCC:
    • ConnectionUri: Nenhum. O valor https://ps.compliance.protection.outlook.com/powershell-liveid/ necessário também é o valor padrão, portanto, você não precisa usar o parâmetro ConnectionUri em ambientes Microsoft 365 ou Microsoft 365 GCC.
    • AzureADAuthorizationEndpointUri: nenhum. O valor https://login.microsoftonline.com/organizationsnecessário, mas também é o valor padrão, portanto, você não precisa usar o parâmetro AzureADAuthorizationEndpointUri em ambientes Microsoft 365 ou Microsoft 365 GCC.
  • 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 operado pela 21Vianet:
    • ConnectionUri: https://ps.compliance.protection.partner.outlook.cn/powershell-liveid
    • AzureADAuthorizationEndpointUri: https://login.chinacloudapi.cn/organizations^*

  ^* O valor AzureADAuthorizationEndpointUri que termina em /organizations permite apenas contas corporativas ou de estudante. O valor de URI mais antigo que termina em /common ainda funciona, mas pode solicitar que você escolha entre uma conta pessoal e uma conta corporativa ou de estudante. Recomendamos o valor URI /organizations em cenários corporativos onde as contas de consumidor devem ser excluídas.

• Se você estiver atrás de um servidor proxy, poderá usar o parâmetro PSSessionOption no comando de conexão. Primeiro, execute este comando: $ProxyOptions = New-PSSessionOption -ProxyAccessType <Value>, em que <Value> é IEConfig, WinHttpConfig, ou AutoDetect. Em seguida, use o valor $ProxyOptions do parâmetro PSSessionOption . Para saber mais, confira New-PSSessionOption.

• Dependendo da natureza da sua organização, você poderá omitir o parâmetro UserPrincipalName na próxima etapa. Em vez disso, insira o nome de usuário e a senha ou selecione as credenciais armazenadas depois de executar o comando Connect-IPPSSession. Se não funcionar, será necessário usar o parâmetro UserPrincipalName.

• Se não estiver usando a MFA, você pode usar o parâmetro Credential em vez do parâmetro UserPrincipalName. Primeiro, execute o comando $Credential = Get-Credential, insira seu nome de usuário e senha e use o nome da variável para o parâmetro Credential (-Credential $Credential). Se não funcionar, será necessário usar o parâmetro UserPrincipalName.

Conecte-se ao PowerShell de Segurança & Conformidade com um prompt de entrada interativo

1. Os exemplos a seguir funcionam no Windows PowerShell 5.1 e PowerShell 7 para contas com ou sem MFA:

   • Este exemplo se conecta ao PowerShell de Segurança e Conformidade em uma organização do Microsoft 365 ou Microsoft 365 GCC:

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

   • Este exemplo se conecta ao PowerShell de Segurança e Conformidade em uma organização Microsoft GCC High:

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

   • Este exemplo se conecta ao PowerShell de Segurança e Conformidade em uma organização do 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
     

   • Este exemplo se conecta ao PowerShell de Segurança e Conformidade em um Office 365 operado pela organização 21Vianet:

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

2. Na janela de entrada que é aberta, insira sua senha e selecione Entrar.

   

   Observação

   No PowerShell 7, o SSO (logon único) baseado em navegador é usado por padrão, portanto, o prompt de entrada é aberto no navegador da Web padrão, em vez de uma caixa de diálogo autônoma.

3. Somente MFA: um código de verificação é gerado e entregue com base na opção de resposta configurada para sua conta (por exemplo, uma mensagem de texto ou o aplicativo Microsoft Authenticator em seu dispositivo).

   Na janela de verificação que é aberta, insira o código de verificação e selecione Verificar.

   

Conectar-se ao PowerShell de Segurança & Conformidade sem um prompt de entrada (scripts autônomos)

Para obter instruções completas, consulte Autenticação somente do aplicativo para scripts autônomos no Exchange Online PowerShell e Conformidade do & Segurança no PowerShell.

Conectar-se ao PowerShell de Segurança & Conformidade em organizações de clientes

Os procedimentos nesta seção exigem a versão 3.0.0 ou posterior do módulo.

No PowerShell de Segurança & Conformidade, você precisa usar o AzureADAuthorizationEndpointUri com o parâmetro DelegatedOrganization .

Para obter mais informações sobre parceiros e organizações de clientes, consulte os seguintes artigos:

• O que é o programa CSP (Provedor de Soluções na Nuvem)?
• Introdução aos GDAP (privilégios de administrador delegado granular)

Este exemplo se conecta às organizações do cliente nos seguintes cenários:

• Conecte-se a uma organização do cliente usando uma conta CSP.

• Conecte-se a uma organização do cliente usando um GDAP.

• Conectar-se a uma organização do cliente como convidado.

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

Etapa 3: Desconecte-se quando terminar

Certifique-se de desconectar a sessão quando terminar. Se você fechar a janela do PowerShell sem desconectar a sessão, poderá usar todas as sessões disponíveis e precisará aguardar até que as sessões expirem. Para desconectar a sessão, execute o seguinte comando:

Disconnect-ExchangeOnline

Para desconectar silenciosamente sem um prompt de confirmação, execute o seguinte comando:

Disconnect-ExchangeOnline -Confirm:$false

Observação

O comando disconnect provavelmente falhará se o caminho do perfil da conta usada para conectar contiver caracteres especiais do PowerShell (por exemplo, $). A solução alternativa é conectar-se usando uma conta diferente que não tenha caracteres especiais no caminho do perfil.

Como você sabe que se conectou com êxito?

Os cmdlets do PowerShell de Segurança e Conformidade são importados para sua sessão local do Windows PowerShell e rastreados por uma barra de progresso. Se nenhum erro aparecer, você se conectou com êxito. Um teste rápido é executar um cmdlet do PowerShell de segurança e conformidade, por exemplo, Get-RetentionCompliancePolicy, e ver os resultados.

Caso você receba erros, verifique os seguintes requisitos:

• Um problema comum é uma senha incorreta. Execute as três etapas novamente e preste muita atenção ao nome de usuário e à senha que você usa.

• A conta que você usa para se conectar deve estar habilitada para o PowerShell. Para obter mais informações, confira Habilitar ou desabilitar o acesso ao PowerShell do Exchange Online.

• O tráfego da porta TCP 80 precisa estar aberto entre seu computador local e o Microsoft 365. Provavelmente ele está aberto, mas é algo a ser considerado caso a sua organização tenha uma política de acesso à Internet restritiva.

• As conexões baseadas em REST para o PowerShell de Segurança & Conformidade exigem o módulo PowerShellGet. Por dependência, o módulo PowerShellGet requer o módulo PackageManagement. Você receberá erros se tentar se conectar sem ter os dois módulos instalados. Por exemplo, você pode ver o seguinte erro:

  O termo 'Update-ModuleManifest' não é reconhecido como o nome de um cmdlet, função, arquivo de script ou programa operável. Verifique a ortografia do nome ou, se um caminho foi incluído, verifique se o caminho está correto e tente novamente.

  Para obter mais informações sobre os requisitos do módulo PowerShellGet e PackageManagement, consulte PowerShellGet para conexões baseadas em REST no Windows.

• Talvez você não consiga se conectar se o endereço IP do cliente for alterado durante a solicitação de conexão. A falha ocorrerá se sua organização usar um pool SNAT (conversão de endereços de rede) de origem com vários endereços IP. O erro de conexão parece com o seguinte:

  A solicitação do Shell Remoto do Windows com ID> ShellId <falhou porque o shell não foi encontrado no servidor. As possíveis causas são: o ShellId especificado está incorreto ou o shell não existe mais no servidor. Forneça o ShellId correto ou crie um novo shell e repita a operação.

  Para corrigir o problema, execute uma das seguintes etapas:

  • Use um pool SNAT que contenha um único endereço IP.
  • Forçar o uso de um endereço IP específico para conexões com o ponto de extremidade do PowerShell de Segurança & Conformidade.