Conectar-se ao PowerShell de Segurança e Conformidade

  • Artigo

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

O módulo Exchange Online PowerShell usa a autenticação moderna para se conectar a todos os ambientes do PowerShell relacionados ao Exchange no Microsoft 365: Exchange Online PowerShell, Security & Compliance PowerShell e o PowerShell (EOP) autônomo de Proteção do Exchange Online. Para obter mais informações sobre o módulo Exchange Online PowerShell, consulte Sobre o módulo Exchange Online PowerShell.

Para se conectar ao Security & Compliance PowerShell para automação, consulte Autenticação somente aplicativo para scripts autônomos.

Do que você precisa saber para começar?

Etapa 1: carregar o módulo Exchange Online PowerShell

Observação

Se o módulo já estiver instalado, normalmente você pode ignorar essa etapa e executar Connect-IPPSSession sem carregar manualmente o módulo primeiro.

Depois de 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 connect provavelmente falharão se o caminho de perfil da conta que você usou para se 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.

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

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

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

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

  • Os valores de ConnectionUri e AzureADAuthorizationEndpointUri necessários dependem da natureza da organização do Microsoft 365. Os valores comuns são descritos na seguinte lista:

    • 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 do Microsoft 365 ou do Microsoft 365 GCC.
      • AzureADAuthorizationEndpointUri: Nenhum. O valor https://login.microsoftonline.com/common necessário 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/common
    • Microsoft 365 DoD:
      • ConnectionUri: https://l5.ps.compliance.protection.office365.us/powershell-liveid/
      • AzureADAuthorizationEndpointUri: https://login.microsoftonline.us/common
    • Office 365 operado pela 21Vianet:
      • ConnectionUri: https://ps.compliance.protection.partner.outlook.cn/powershell-liveid
      • AzureADAuthorizationEndpointUri: https://login.chinacloudapi.cn/common

  • 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, WinHttpConfigou AutoDetect. Em seguida, use o valor $ProxyOptions para o 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.

Conectar-se ao PowerShell de Conformidade do & de Segurança com um prompt de logon interativo

  1. Os exemplos a seguir funcionam no Windows PowerShell 5.1 e no 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/common

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

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

  2. Na janela de entrada exibida, insira sua senha e, em seguida, clique em Entrar.

    Insira sua senha na janela Entrar na sua conta.

    Observação

    No PowerShell 7, o SSO (logon único) baseado no 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. Apenas para MFA: um código de verificação é gerado e fornecido com base na opção de resposta de verificação que está configurada para sua conta (por exemplo, uma mensagem de texto ou o aplicativo Microsoft Authenticator em seu dispositivo).

    Na janela de verificação exibida, digite o código de verificação e, em seguida, clique em Verificar.

    Insira seu código de verificação na janela Entrar na sua conta.

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

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

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

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

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

Para obter mais informações sobre parceiros e organizações de clientes, confira os seguintes tópicos:

Este exemplo se conecta a organizações de clientes nos seguintes cenários:

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

  • Conecte-se a uma organização de clientes usando um GDAP.

  • Conecte-se a uma organização do cliente como usuário convidado.

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

Etapa 3: desconectar quando terminar

Desconecte 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 para você e precisará aguardar a expiração das sessões. 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 de desconexão provavelmente falhará se o caminho de perfil da conta que você usou para se 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 você não receber nenhum erro, 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 com o Security & Compliance PowerShell exigem o módulo PowerShellGet e, por dependência, o módulo PackageManagement, portanto, você receberá erros se tentar se conectar sem instalá-los. 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. Isso pode acontecer se sua organização usar um pool de SNAT (conversão de endereços de rede de origem) contendo vários endereços IP. O erro de conexão parece com o seguinte:

    A solicitação do Shell Remoto do Windows com iD> do 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, use um pool de SNAT que contenha um único endereço IP ou force o uso de um endereço IP específico para conexões com o ponto de extremidade do PowerShell de Conformidade e Segurança.