连接 Exchange Online PowerShell

本文包含有关如何使用 Exchange Online PowerShell 模块连接到 Exchange Online PowerShell 的说明,无论该模块是否具有多重身份验证 (MFA) 。

Exchange Online PowerShell 模块使用新式身份验证连接到 Microsoft 365 中的所有与 Exchange 相关的 PowerShell 环境:Exchange Online PowerShell、安全性 & 合规性 PowerShell 和独立的 Exchange Online Protection (EOP) PowerShell。 有关 Exchange Online PowerShell 模块的详细信息,请参阅 关于 Exchange Online PowerShell 模块

若要连接到 Exchange Online PowerShell 实现自动化,请参阅无人参与脚本的仅限应用身份验证和使用 Azure 托管标识连接到 Exchange Online PowerShell

若要从 C# 连接到 Exchange Online PowerShell,请参阅 使用 C# 连接到 Exchange Online PowerShell

开始前,有必要了解什么?

提示

是否有任何疑问? 请在 Exchange Online 论坛中提问。

步骤 1:加载 Exchange Online PowerShell 模块

注意

如果模块已安装,通常可以跳过此步骤并运行 Connect-ExchangeOnline ,而无需先手动加载模块。

安装模块后,打开 PowerShell 窗口,并通过运行以下命令加载模块:

Import-Module ExchangeOnlineManagement

步骤 2:连接并进行身份验证

注意

如果用于连接的帐户的配置文件路径包含特殊 PowerShell 字符, (例如,) , $ 连接命令可能会失败。 解决方法是使用配置文件路径中没有特殊字符的其他帐户进行连接。

需要运行的命令使用以下语法:

Connect-ExchangeOnline -UserPrincipalName <UPN> [-ExchangeEnvironmentName <Value>] [-ShowBanner:$false] [-DelegatedOrganization <String>] [-SkipLoadingFormatData]

有关详细的语法和参数信息,请参阅 Connect-ExchangeOnline

  • <UPN> 是用户主体名称格式的帐户, (例如 navin@contoso.onmicrosoft.com) 。

  • EXO V3 模块 (v3.0.0 或更高版本) 和 基本身份验证 (远程 PowerShell) 连接到 Exchange Online 时,你仅使用 REST API cmdlet。 有关详细信息,请参阅 EXO V3 模块中的 REST API 连接

  • 如果使用 ExchangeEnvironmentName 参数,则无需使用 ConnectionUriAzureADAuthorizationEndPointUrl 参数。 下表介绍了 ExchangeEnvironmentName 参数的通用值:

    环境
    Microsoft 365 或 Microsoft 365 GCC 不适用*
    Microsoft 365 GCC High O365USGovGCCHigh
    Microsoft 365 DoD O365USGovDoD
    Office 365 德国 O365GermanyCloud
    由世纪互联运营的 Office 365 O365China

    * 所需的值 O365Default 也是默认值,因此无需在 Microsoft 365 或 Microsoft 365 GCC 环境中使用 ExchangeEnvironmentName 参数。

  • DelegatedOrganization 参数指定要作为授权的 Microsoft 合作伙伴管理的客户组织。 有关详细信息,请参阅 本文后面的连接示例

  • 根据组织的性质,可以在连接命令中省略 UserPrincipalName 参数。 而是在运行 Connect-ExchangeOnline 命令后输入用户名和密码或选择存储的凭据。 如果不起作用,则需要使用参数 UserPrincipalName 参数。

  • 如果不使用 MFA,则应能够使用 Credential 参数,而不是 UserPrincipalName 参数。 首先,运行命令 $Credential = Get-Credential,输入用户名和密码,然后使用 凭据参数 ( ) 的变量-Credential $Credential。 如果不起作用,则需要使用参数 UserPrincipalName 参数。

  • 使用 SkipLoadingFormatData 开关避免从 Windows 服务内连接到 Exchange Online PowerShell 时出错。

  • 在 PowerShell 7 中使用 模块需要版本 2.0.4 或更高版本。

以下部分中的连接示例使用新式身份验证,并且无法使用基本身份验证。

使用交互式登录提示连接到 Exchange Online PowerShell

  1. 以下示例适用于具有或不带 MFA 的帐户的 Windows PowerShell 5.1 和 PowerShell 7:

    • 此示例连接到 Microsoft 365 或 Microsoft 365 GCC 组织中的 Exchange Online PowerShell

      Connect-ExchangeOnline -UserPrincipalName navin@contoso.onmicrosoft.com
      
    • 此示例连接到 Microsoft GCC High 组织中的 Exchange Online PowerShell

      Connect-ExchangeOnline -UserPrincipalName laura@blueyonderairlines.us -ExchangeEnvironmentName O365USGovGCCHigh
      
    • 此示例连接到 Microsoft 365 DoD 组织中的 Exchange Online PowerShell

      Connect-ExchangeOnline -UserPrincipalName julia@adatum.mil -ExchangeEnvironmentName O365USGovDoD
      
    • 此示例连接到 Office 365 Germany 组织中的 Exchange Online PowerShell

      Connect-ExchangeOnline -UserPrincipalName lukas@fabrikam.de -ExchangeEnvironmentName O365GermanyCloud
      
  2. 在打开的登录窗口中,输入密码,然后单击“登录”。

    在“登录您的帐户”窗口中输入密码。

    注意

    在 PowerShell 7 中,默认使用基于浏览器的单一登录 (SSO) ,因此登录提示会在默认 Web 浏览器中打开,而不是在独立对话框中打开。

  3. 仅 MFA:根据为帐户配置的回复选项(例如,你的设备上短信或 Microsoft Authenticator 应用)生成并传递验证码。

    在打开的验证窗口中,输入验证码,然后单击 验证

    在“登录您的账户”窗口中输入验证码。

PowerShell 7 独占连接方法

  • 对于 没有 MFA 的帐户,在 PowerShell 7 中,此示例提示在 PowerShell 窗口中输入凭据:

    Connect-ExchangeOnline -UserPrincipalName navin@contoso.onmicrosoft.com -InlineCredential
    
  • 在具有或不带 MFA 的帐户的 PowerShell 7 中,此示例使用另一台计算机进行身份验证并完成连接。 通常,在没有 Web 浏览器的计算机上使用此方法, (用户无法在 PowerShell 7) 中输入其凭据:

    1. 在要连接的计算机上运行以下命令:

      Connect-ExchangeOnline -Device
      

      连接命令在以下输出处等待:

      若要登录,请使用 Web 浏览器打开页面 https://microsoft.com/devicelogin 并输入代码 <XXXXXXXXX> 进行身份验证。

      记下 <XXXXXXXXX> 代码值。

    2. 在具有 Web 浏览器和 Internet 访问的任何其他设备上,打开 https://microsoft.com/devicelogin 并输入 <上一步中的 XXXXXXXXX> 代码值。

    3. 在生成的页面上输入凭据。

    4. 在确认提示中,单击“ 继续”。 下一条消息应指示成功,你可以关闭浏览器或选项卡。

    5. 步骤 1 中的命令继续将你连接到 Exchange Online PowerShell。

在没有登录提示的情况下连接到 Exchange Online PowerShell (无人参与的脚本)

有关完整说明,请参阅 Exchange Online PowerShell 中无人参与脚本的仅限应用身份验证和安全性 & 合规性 PowerShell

在客户组织中连接到 Exchange Online PowerShell

有关合作伙伴和客户组织的详细信息,请参阅以下主题:

此示例在以下方案中连接到客户组织:

  • 使用 CSP 帐户连接到客户组织。

  • 使用 GDAP 连接到客户组织。

  • 以来宾用户身份连接到客户组织。

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

使用托管标识连接到 Exchange Online PowerShell

有关详细信息,请参阅 使用 Azure 托管标识连接到 Exchange Online PowerShell

  • 系统分配的托管标识:

    Connect-ExchangeOnline -ManagedIdentity -Organization "cohovinyard.onmicrosoft.com"
    
  • 用户分配的已分配托管标识:

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

步骤 3:完成后断开连接

完成后,请务必断开会话的连接。 如果在未断开会话连接的情况下关闭 PowerShell 窗口,则可能会用尽所有可用会话,并且需要等待会话过期。 若要断开会话连接,请运行以下命令:

Disconnect-ExchangeOnline

若要在无确认提示的情况下以无提示方式断开连接,请运行以下命令:

Disconnect-ExchangeOnline -Confirm:$false

注意

如果用于连接的帐户的配置文件路径包含特殊 PowerShell 字符, (例如,) , $ 则 disconnect 命令可能会失败。 解决方法是使用配置文件路径中没有特殊字符的其他帐户进行连接。

如何知道已成功连接?

如果未收到任何错误,则说明已成功连接。 快速测试是运行 Exchange Online PowerShell cmdlet(例如 Get-AcceptedDomain),并查看结果。

如果收到错误,则查看以下要求:

  • 常见问题是密码错误。 再次运行连接步骤,并密切关注使用的用户名和密码。

  • 必须启用用于连接到的帐户才能访问 PowerShell。 有关详细信息,请参阅启用或禁用对 Exchange Online PowerShell 的访问

  • 需要在本地计算机和 Microsoft 365 之间打开 TCP 端口 80 通信。 它可能已经打开了,但是要考虑您的组织是否存在严格的 Internet 访问政策。

  • 如果你的组织使用联合身份验证,并且标识提供者 (IDP) 和/或安全令牌服务 (STS) 未公开提供,则无法使用联合帐户连接到 Exchange Online PowerShell。 而是应该在 Microsoft 365 中创建并使用非联合帐户来连接到 Exchange Online PowerShell。

  • 与 Exchange Online PowerShell 的基于 REST 的连接需要 PowerShellGet 模块,根据依赖项,需要 PackageManagement 模块,因此,如果尝试连接而不安装它们,将收到错误。 例如,你可能会看到以下错误:

    不能将术语“Update-ModuleManifest”识别为 cmdlet、函数、脚本文件或可操作程序的名称。 检查名称的拼写,或者是否包含路径,验证路径是否正确,然后重试。

    有关 PowerShellGet 和 PackageManagement 模块要求的详细信息,请参阅 Windows 中基于 REST 的连接的 PowerShellGet

  • 连接后,可能会收到如下所示的错误:

    无法加载文件或程序集“System.IdentityModel.Tokens.Jwt,Version=<Version,Culture>=neutral,PublicKeyToken=<TokenValue>”。 找不到或加载特定文件。

    当 Exchange Online PowerShell 模块与导入到运行空间中的另一个模块发生冲突时,会发生此错误。 在导入其他模块之前,请尝试在新的 Windows PowerShell 窗口中进行连接。

附录:新旧连接方法的比较

本部分尝试比较 Exchange Online PowerShell 模块已替换的旧连接方法。 基本身份验证和 OAuth 令牌过程包含在内,仅供历史参考,不再受支持。

无需多重身份验证进行连接

  • 带有交互式凭据提示的 Exchange Online PowerShell 模块

    Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com
    
  • 没有交互式凭据提示的 Exchange Online PowerShell 模块

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

    $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
    
  • 具有 OAuth 令牌的 New-PSSession

    $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
    

使用多重身份验证进行连接

  • 带有交互式凭据提示的 Exchange Online PowerShell 模块

    Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com
    
  • 基本身份验证:不可用。

  • 具有 OAuth 令牌的 New-PSSession:不可用。

使用 CSP 帐户连接到客户组织

  • Exchange Online PowerShell 模块

    Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com -DelegatedOrganization delegated.onmicrosoft.com
    
  • 基本身份验证

    $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
    
  • 具有 OAuth 令牌的 New-PSSession

    $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
    

使用 GDAP 连接到客户组织

  • Exchange Online PowerShell 模块

    Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com -DelegatedOrganization delegated.onmicrosoft.com
    
  • 基本身份验证

    $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
    
  • 具有 OAuth 令牌的 New-PSSession

    $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
    

以来宾用户身份连接到客户组织

  • Exchange Online PowerShell 模块

    Connect-ExchangeOnline -UserPrincipalName admin@contoso.onmicrosoft.com -DelegatedOrganization delegated.onmicrosoft.com
    
  • 基本身份验证

    $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
    
  • 具有 OAuth 令牌的 New-PSSession

    $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
    

连接以运行无人参与的脚本

  • Exchange Online PowerShell 模块

    • 证书指纹

      注意

      CertificateThumbprint 参数仅在 Microsoft Windows 中受支持。

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

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

      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"
      

    有关详细信息,请参阅 Exchange Online PowerShell 中无人参与脚本的仅限应用的身份验证和安全性 & 合规性 PowerShell

  • 基本身份验证

    $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
    
  • 具有 OAuth 令牌的 New-PSSession

    $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
    

使用托管标识进行连接

  • Exchange Online PowerShell 模块

    • 系统分配的托管标识

      Connect-ExchangeOnline -ManagedIdentity -Organization "contoso.onmicrosoft.com"
      
    • 用户分配的托管标识

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

    有关详细信息,请参阅 使用 Azure 托管标识连接到 Exchange Online PowerShell

  • 基本身份验证:不可用。

  • 具有 OAuth 令牌的 New-PSSession:不可用。