Conectar-se ao Exchange Online PowerShell

Este artigo contém instruções de como se conectar ao Exchange Online 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, PowerShell de Conformidade de Segurança & e PowerShell de Proteção do Exchange Online autônomo (EOP). Para obter mais informações sobre o módulo Exchange Online PowerShell, consulte Sobre o módulo Exchange Online PowerShell.

Observação

A versão 2.0.5 e anterior é conhecida como o módulo Exchange Online PowerShell V2 (abreviado como o módulo EXO V2). A versão 3.0.0 e posterior é conhecida como o módulo Exchange Online PowerShell V3 (abreviado como o módulo EXO V3).

Para se conectar ao Exchange Online PowerShell para automação, confira Autenticação somente aplicativo para scripts autônomos e Usar identidades gerenciadas do Azure para se conectar ao Exchange Online PowerShell.

Para se conectar ao Exchange Online PowerShell do C#, consulte Usar C# para se conectar ao Exchange Online PowerShell.

Para usar as instruções de conexão remota do PowerShell mais antigo e menos seguro que será eventualmente preterido, confira Autenticação básica – Conectar ao Exchange Online PowerShell.

Para usar o antigo módulo Exchange Online Remote PowerShell para se conectar ao Exchange Online PowerShell usando MFA, confira Módulo V1 – Conectar ao Exchange Online PowerShell usando MFA. Essa versão mais antiga do módulo será eventualmente removida.

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

  Se você estiver usando o módulo EXO V3 (v3.0.0 ou v2.0.6-PreviewX) e não usar a opção UseRPSSession no comando Connect-ExchangeOnline , você terá acesso apenas aos cmdlets da API REST. Para obter mais informações, consulte Atualizações para a versão 3.0.0 (o módulo EXO V3).

  O suporte remoto do PowerShell no Exchange Online PowerShell será preterido. Para obter mais informações, consulte Anunciando a preterição do protocolo RPS (Remote PowerShell) no Exchange Online PowerShell.

• 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, confira Permissões no Exchange Online.

  Para localizar as permissões necessárias para executar cmdlets específicos do Exchange Online, consulte Encontre as permissões necessárias para executar qualquer cmdlet do Exchange.

• Se sua organização for Exchange local e você tiver direitos autorais do Exchange Empresa com licenças de Serviços para Proteção do Exchange Online (EOP), as instruções de conexão do Windows PowerShell EOP são iguais às do Exchange Online Windows PowerShell, conforme descrito neste artigo.

Dica

Está com problemas? Pergunte no fórum do Exchange Online.

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-ExchangeOnline 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-ExchangeOnline -UserPrincipalName <UPN> [-UseRPSSession] [-ExchangeEnvironmentName <Value>] [-ShowBanner:$false] [-DelegatedOrganization <String>] [-PSSessionOption $ProxyOptions]

Para informações detalhadas sobre sintaxe e parâmetros, confira Connect-ExchangeOnline.

Observações:

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

• Com o módulo EXO V3 (v3.0.0 ou v2.0.6-PreviewX), se você não usar a opção UseRPSSession , usará somente cmdlets de API REST. Para obter mais informações, consulte Atualizações para a versão 3.0.0 (o módulo EXO V3).

• Quando você usa o parâmetro ExchangeEnvironmentName, não é necessário usar os parâmetros ConnectionUri ou AzureADAuthorizationEndPointUrl. Valores comuns para o parâmetro ExchangeEnvironmentName são descritos na tabela a seguir:

  Ambiente	Valor
  Microsoft 365 ou Microsoft 365 GCC	n/d*
  Microsoft 365 GCC High	O365USGovGCCHigh
  Microsoft 365 DoD	O365USGovDoD
  Office 365 Alemanha	O365GermanyCloud
  Office 365 operado pela 21Vianet	O365China

  ^* O valor O365Default necessário também é o valor padrão, portanto, você não precisa usar o parâmetro ExchangeEnvironmentName em ambientes do Microsoft 365 ou do Microsoft 365 GCC.

• O parâmetro DelegatedOrganization especifica a organização do cliente que você deseja gerenciar como um parceiro autorizado da Microsoft. Para obter mais informações, confira os exemplos de conexão mais adiante neste artigo.

• Se você estiver atrás de um servidor proxy, poderá usar o parâmetro PSSessionOption no comando de conexão, mas somente se você também usar a opção UseRPSSession . 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ê pode ser capaz de omitir o parâmetro UserPrincipalName no comando de conexão. Em vez disso, você insere o nome de usuário e a senha ou seleciona as credenciais armazenadas após executar o comando Connect-ExchangeOnline. 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.

• Usar o módulo no PowerShell 7 requer a versão 2.0.4 ou posterior.

Os exemplos de conexão nas seções a seguir usam autenticação moderna e são incapazes de usar a autenticação básica.

Conectar-se ao Exchange Online PowerShell 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 Exchange Online PowerShell em uma organização do Microsoft 365 ou Microsoft 365 GCC:

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

   • Este exemplo se conecta ao Exchange Online PowerShell em uma organização do Microsoft GCC High:

     Connect-ExchangeOnline -UserPrincipalName laura@blueyonderairlines.us -ExchangeEnvironmentName O365USGovGCCHigh
     

   • Este exemplo se conecta ao Exchange Online PowerShell em uma organização do Microsoft 365 DoD:

     Connect-ExchangeOnline -UserPrincipalName julia@adatum.mil -ExchangeEnvironmentName O365USGovDoD
     

   • Este exemplo se conecta ao Exchange Online PowerShell em uma organização do Office 365 Alemanha:

     Connect-ExchangeOnline -UserPrincipalName lukas@fabrikam.de -ExchangeEnvironmentName O365GermanyCloud
     

2. 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.

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.

   

Métodos de conexão exclusivos do PowerShell 7

• No PowerShell 7 para contas sem MFA, este exemplo solicita credenciais na janela do PowerShell:

  Connect-ExchangeOnline -UserPrincipalName navin@contoso.onmicrosoft.com -InlineCredential
  

• No PowerShell 7 para contas com ou sem MFA, este exemplo usa outro computador para autenticar e concluir a conexão. Normalmente, você usa esse método em computadores que não têm navegadores da Web (os usuários não podem inserir suas credenciais no PowerShell 7):

  1. Execute o seguinte comando no computador em que você deseja se conectar:

     Connect-ExchangeOnline -Device
     

     O comando de conexão aguarda a seguinte saída:

     Para entrar, use um navegador da Web para abrir a página https://microsoft.com/devicelogin e insira o código <XXXXXXXXX para> autenticar.

     Observe o valor de <código XXXXXXXXX> .

  2. Em qualquer outro dispositivo com um navegador da Web e acesso à Internet, abra https://microsoft.com/devicelogin e insira o <valor de código XXXXXXXXX> da etapa anterior.

  3. Insira suas credenciais nas páginas resultantes.

  4. No prompt de confirmação, clique em Continuar. A próxima mensagem deve indicar êxito e você pode fechar o navegador ou a guia.

  5. O comando da etapa 1 continua a conectá-lo ao Exchange Online PowerShell.

Conectar-se ao Exchange Online PowerShell sem um prompt de logon (scripts autônomos)

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

Importante

O exemplo a seguir também se conecta sem um prompt de logon, mas as credenciais são armazenadas localmente, portanto esse método não é seguro. Considere usar esse método apenas para breves finalidades de teste.

$secpasswd = ConvertTo-SecureString -String '<YourPasswordHere>' -AsPlainText -Force 

$o365cred = New-Object System.Management.Automation.PSCredential ("navin@contoso.onmicrosoft.com", $secpasswd) 

Connect-ExchangeOnline -Credential $o365cred

Conectar-se ao Exchange Online PowerShell em organizações de clientes

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-ExchangeOnline -UserPrincipalName navin@contoso.onmicrosoft.com -DelegatedOrganization adatum.onmicrosoft.com
  

Conectar-se ao Exchange Online PowerShell usando identidade gerenciada

Para obter mais informações, confira Usar identidades gerenciadas do Azure para se conectar ao Exchange Online PowerShell.

• Identidade gerenciada atribuída pelo sistema:

  Connect-ExchangeOnline -ManagedIdentity -Organization "cohovinyard.onmicrosoft.com"
  

• Identidade gerenciada atribuída pelo usuário:

  Connect-ExchangeOnline -ManagedIdentity -Organization "constoso.onmicrosoft.com" -ManagedIdentityAccountId <ManagedIdentityAccountIdGuid>
  

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 comando a seguir.

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?

Se você não receber nenhum erro, você se conectou com êxito. Um teste rápido é executar um cmdlet Exchange Online PowerShell, por exemplo, Get-AcceptedDomain e ver os resultados.

Caso você receba erros, verifique os seguintes requisitos:

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

• Para ajudar a evitar ataques do DoS (negação de serviço), ao se conectar usando o comutador UseRPSSession, você está limitado a cinco conexões abertas para Exchange Online PowerShell.

• A conta que você usa para conectar deve estar habilitada para o PowerShell remoto. 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.

• Se sua organização usa autenticação federada e seu provedor de identidade (IDP) e/ou serviço de token de segurança (STS) não estiver disponível ao público, você não poderá usar uma conta federada para se conectar ao PowerShell do Exchange Online. Em vez disso, crie e use uma conta não federada no Microsoft 365 para se conectar ao PowerShell do Exchange Online.

Apêndice: comparação de métodos de conexão antigos e novos

Esta seção tenta comparar métodos de conexão mais antigos que foram substituídos pelo módulo Exchange Online PowerShell. Os procedimentos básicos de autenticação e token OAuth são incluídos apenas para referência histórica e não têm mais suporte.

Conectar sem autenticação multifator

• Exchange Online módulo do PowerShell com prompt de credencial interativo:

  Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com
  

• Exchange Online módulo do PowerShell sem prompt de credencial interativo:

  $secpasswd = ConvertTo-SecureString '<Password>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $secpasswd)
  
  Connect-ExchangeOnline -Credential $o365cred
  

• Autenticação básica:

  $secpasswd = ConvertTo-SecureString '<Password>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $secpasswd)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/ -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

• New-PSSession com token OAuth:

  $oauthTokenAsPassword = ConvertTo-SecureString '<EncodedOAuthToken>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $oauthTokenAsPassword)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/?BasicAuthToOAuthConversion=true -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

Conectar-se à autenticação multifator

• Exchange Online módulo do PowerShell com prompt de credencial interativo:

  Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com
  

• Autenticação básica: não disponível.

• New-PSSession com token OAuth: não disponível.

Conectar-se a uma organização de clientes com uma conta CSP

• Exchange Online módulo do PowerShell:

  Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com -DelegatedOrganization delegated.onmicrosoft.com
  

• Autenticação básica:

  $secpasswd = ConvertTo-SecureString '<Password>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $secpasswd)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/?DelegatedOrg=delegated.onmicrosoft.com&email=SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@delegated.onmicrosoft.com -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

• New-PSSession com token OAuth:

  $oauthTokenAsPassword = ConvertTo-SecureString '<EncodedOAuthToken>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $oauthTokenAsPassword)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/? DelegatedOrg=delegated.onmicrosoft.com&BasicAuthToOAuthConversion=true&email=SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@delegated.onmicrosoft.com -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

Conectar-se a uma organização de clientes usando o GDAP

• Exchange Online módulo do PowerShell:

  Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com -DelegatedOrganization delegated.onmicrosoft.com
  

• Autenticação básica:

  $secpasswd = ConvertTo-SecureString '<Password>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $secpasswd)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/?DelegatedOrg=delegated.onmicrosoft.com&email=SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@delegated.onmicrosoft.com -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

• New-PSSession com token OAuth:

  $oauthTokenAsPassword = ConvertTo-SecureString '<EncodedOAuthToken>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $oauthTokenAsPassword)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/? DelegatedOrg=delegated.onmicrosoft.com&BasicAuthToOAuthConversion=true&email=SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@delegated.onmicrosoft.com -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

Conectar-se a uma organização do cliente como usuário convidado

• Exchange Online módulo do PowerShell:

  Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com -DelegatedOrganization delegated.onmicrosoft.com
  

• Autenticação básica:

  $secpasswd = ConvertTo-SecureString '<Password>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $secpasswd)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/?DelegatedOrg=delegated.onmicrosoft.com&email=SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@delegated.onmicrosoft.com -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

• New-PSSession com token OAuth:

  $oauthTokenAsPassword = ConvertTo-SecureString "<EncodedOAuthToken>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $oauthTokenAsPassword)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/?DelegatedOrg=delegated.onmicrosoft.com&BasicAuthToOAuthConversion=true&email=SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@delegated.onmicrosoft.com -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

Conectar-se para executar scripts autônomos

• Exchange Online módulo do PowerShell:

  • Impressão digital do certificado:

    Connect-ExchangeOnline -CertificateThumbPrint "012THISISADEMOTHUMBPRINT" -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contoso.onmicrosoft.com"
    

  • Objeto certificado:

    Connect-ExchangeOnline -Certificate <%X509Certificate2Object%> -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contoso.onmicrosoft.com"
    

  • Arquivo de certificado:

    Connect-ExchangeOnline -CertificateFilePath "C:\Users\navin\Desktop\automation-cert.pfx" -CertificatePassword (ConvertTo-SecureString -String "<Password>" -AsPlainText -Force) -AppID "36ee4c6c-0812-40a2-b820-b22ebd02bce3" -Organization "contoso.onmicrosoft.com"
    

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

• Autenticação básica:

  $secpasswd = ConvertTo-SecureString '<Password>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $secpasswd)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/ -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

• New-PSSession com token OAuth:

  $oauthTokenAsPassword = ConvertTo-SecureString '<EncodedOAuthToken>' -AsPlainText -Force
  
  $o365cred = New-Object System.Management.Automation.PSCredential ("admin@contoso.onmicrosoft.com", $oauthTokenAsPassword)
  
  $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/PowerShell-LiveID/?BasicAuthToOAuthConversion=true&email=SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com -Credential $o365cred -Authentication Basic -AllowRedirection
  
  Import-PSSession $Session
  

Conectar usando identidade gerenciada

• Exchange Online módulo do PowerShell:

  • Identidade gerenciada atribuída pelo sistema:

    Connect-ExchangeOnline -ManagedIdentity -Organization "contoso.onmicrosoft.com"
    

  • Identidade gerenciada atribuída pelo usuário:

    Connect-ExchangeOnline -ManagedIdentity -Organization "contoso.onmicrosoft.com" -ManagedIdentityAccountId <UserAssignedManagedIdentityPrincipalIdValue>
    

  Para obter mais informações, confira Usar identidades gerenciadas do Azure para se conectar ao Exchange Online PowerShell.

• Autenticação básica: não disponível.

• New-PSSession com token OAuth: não disponível.