Conectar-se ao PowerShell de Segurança e Conformidade
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?
Os requisitos para instalar e usar o módulo são descritos em Instalar e manter o módulo Exchange Online PowerShell.
Observação
As conexões remotas do PowerShell são preteridas no PowerShell de Conformidade do & de Segurança. Para obter mais informações, consulte Preterimento do Protocolo RPS (Remote PowerShell) no PowerShell de conformidade de & de segurança.
As conexões de API REST no módulo Exchange Online PowerShell V3 exigem os módulos PowerShellGet e PackageManagement. Para obter mais informações, consulte PowerShellGet para conexões baseadas em REST no Windows.
Depois de se conectar, os cmdlets e parâmetros aos quais você tem ou não acesso são controlados pelo controle de acesso baseado em função (RBAC). Para obter mais informações, consulte Permissões no portal de Microsoft Defender e Permissões no portal de conformidade do Microsoft Purview.
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.
- ConnectionUri: Nenhum. O valor
- Microsoft 365 GCC High:
- ConnectionUri:
https://ps.compliance.protection.office365.us/powershell-liveid/
- AzureADAuthorizationEndpointUri:
https://login.microsoftonline.us/common
- ConnectionUri:
- Microsoft 365 DoD:
- ConnectionUri:
https://l5.ps.compliance.protection.office365.us/powershell-liveid/
- AzureADAuthorizationEndpointUri:
https://login.microsoftonline.us/common
- ConnectionUri:
- Office 365 operado pela 21Vianet:
- ConnectionUri:
https://ps.compliance.protection.partner.outlook.cn/powershell-liveid
- AzureADAuthorizationEndpointUri:
https://login.chinacloudapi.cn/common
- ConnectionUri:
- Microsoft 365 ou Microsoft 365 GCC:
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
ouAutoDetect
. 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
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
Na janela de entrada exibida, insira sua senha e, em seguida, clique em Entrar.
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.
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.
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:
- O que é o programa CSP (Provedor de Soluções na Nuvem)?.
- Introdução aos privilégios de administrador delegado granular (GDAP)
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.
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários