如何通过 v2 模块连接到 Exchange Online PowerShell

如果您是 Office 365 管理员，您可能正在使用 PowerShell 脚本来执行各种自动化任务。但是，您不太可能使用 MFA 通过 PowerShell 对无人值守脚本进行身份验证并连接到 Exchange Online。这意味着您的脚本仍在使用基本身份验证。

Microsoft 最初计划于 2020 年 10 月 13 日删除 Exchange Online 的基本身份验证。然后，该计划暂定日期为 2021 年下半年。

迟早，管理员需要重新设计脚本，同时考虑以下因素：

• PowerShell 脚本必须使用现代身份验证，同时保持无人值守运行的能力。
• PowerShell 脚本必须安全地进行身份验证，而无需排除 Office 365 中多重身份验证的服务帐户。

此前，现有解决方案无法满足这两个条件。幸运的是，Microsoft 发布了 Exchange Online V2 PowerShell 模块版本 2.0.3-preview。此新版本添加了使用与 Azure AD 应用关联的基于证书的身份验证的功能。

在本文中，您将了解如何准备使用 EXO V2 模块通过仅限应用程序的现代身份验证来运行 Exchange Online 无人参与脚本。您将学习如何：

• 在 Azure Active Directory 中注册新应用程序并启用其服务主体。
• 分配 API 权限和角色。
• 生成并上传自签名证书。
• 使用应用程序和证书进行身份验证并连接到 Exchange Online PowerShell。

话虽如此，不要指望在本文中看到很多点击说明。大多数演练指令将在 PowerShell 中完成。

先决条件

为了让您成功遵循，请确保满足以下要求。

• 访问具有全局管理员权限的 Office 365 租户。使用非生产/开发租户进行测试。您应该考虑注册 Office 365 试用租户。
• 一台装有 Windows PowerShell 5.1 的 Windows 计算机。在本文中，你将使用运行 Windows 10 版本 1909 的计算机。
• 安装最新的AzureAD PowerShell 模块。本文当前使用的版本是2.0.2.106。
• 代码编辑器，例如 Notepad++、Atom、Windows PowerShell ISE 或 Visual Studio Code。使用您最舒服的任何一个。
• 为您的测试创建一个工作目录。在本文中，工作目录为C:\exo_v2_demo。
• 下载 Create-SelfSignedCertificate.ps1 脚本的副本并将其保存到您的工作目录。在本文中，我们将把脚本保存在工作目录C:\exo_v2_demo中。

使用 PowerShell 设置仅应用程序身份验证

您可能习惯于使用通用帐户（通常称为服务帐户）来运行 PowerShell 脚本。这种类型的帐户本质上是“共享”帐户。任何知道该帐户凭据的人都可以使用它登录并在您的组织中执行各种管理操作；这是一个安全问题。

仅应用程序身份验证尝试解决该安全问题。仅应用程序身份验证需要使用具有服务主体和选定权限和角色的 Azure AD 应用程序。使用令牌或证书进行身份验证。

创建具有 API 权限的 Azure AD 应用程序

第一步是在 Azure AD 中创建具有正确 API 权限的新应用程序。首先，打开提升的 Windows PowerShell（以管理员身份运行）并确保连接到 Azure AD。

下面的代码将在 Azure AD 中注册一个名为 Exo_V2_App 的新应用，并分配 Office 365 Exchange Online API 的 Exchange.ManageAsApp 权限。

如果您希望为应用程序使用不同的名称，请编辑以下代码中的 $appName 变量的值。复制代码并在 PowerShell 中运行它。

# CODE TO REGISTER APP, ASSIGN API PERMISSIONS, AND ENABLE SERVICE PRINCIPAL
## Define the client app name
$appName = 'Exo_V2_App'

## Get the Office 365 Exchange Online API details.
$api = (Get-AzureADServicePrincipal -Filter "AppID eq '00000002-0000-0ff1-ce00-000000000000'")

## Get the API permission ID
$permission = $api.AppRoles | Where-Object { $_.Value -eq 'Exchange.ManageAsApp' }

## Build the API permission object (TYPE: Role = Application, Scope = User)
$apiPermission = [Microsoft.Open.AzureAD.Model.RequiredResourceAccess]@{
    ResourceAppId  = $api.AppId ;
    ResourceAccess = [Microsoft.Open.AzureAD.Model.ResourceAccess]@{
        Id   = $permission.Id ;
        Type = "Role"
    }
}

## Register the new Azure AD App with API Permissions
$myApp = New-AzureADApplication -DisplayName $appName -ReplyUrls 'http://localhost' -RequiredResourceAccess $apiPermission

## Enable the Service Principal
$mySP = New-AzureADServicePrincipal -AppID $myApp.AppID

## Display the new app properties
$myApp | Format-List DisplayName,ObjectID,AppID

下面的演示显示了正在运行的代码。最后，它将显示新应用程序的 DisplayName、ObjectID 和 AppID 属性。 $myApp 变量存储这些属性。 $mySP 变量保存服务主体的属性值。

提示：请确保保存应用程序的属性以供快速参考。

使用下面的此命令导出应用程序的属性值。

$myApp | Export-Csv -NoTypeInformation "$($appName).csv"

将 Azure AD 角色分配给应用程序

创建应用程序后，下一步是将 Azure AD 角色分配给应用程序的服务主体。您需要决定分配给应用程序的角色类型。

Exchange Online V2 支持的有效角色如下。

• 公司管理员
• 合规管理员
• 安全读卡器
• 安全管理员
• 帮助台管理员
• 交换服务管理员
• 全球读者

您应该只分配您认为适合脚本的最低特权角色。在此示例中，下面的代码会将 Exchange 服务管理员角色分配给应用的服务主体。

## The role to assign to your app
$directoryRole = 'Exchange Service Administrator'

## Find the ObjectID of 'Exchange Service Administrator'
$RoleId = (Get-AzureADDirectoryRole | Where-Object {$_.displayname -eq $directoryRole}).ObjectID

## Add the service principal to the directory role
Add-AzureADDirectoryRoleMember -ObjectId $RoleId -RefObjectId $mySP.ObjectID -Verbose

当您在 PowerShell 中运行上述命令时，您应该会看到类似于下面演示中所示的输出。

生成自签名证书并将其附加到应用程序

下一步是生成自签名证书并将该证书附加到您的应用程序。您需要使用 Create-SelfSignedCertificate.ps1 脚本来执行此步骤。

下面的脚本将使用您的应用名称作为主题名称生成自签名证书，例如 Exo_V2_App。该证书的有效期为一 (1) 年。

如果您想更改证书的有效期，则应将 $certYears 值更改为您想要的年数。如果您想对生成的证书 (PFX) 文件使用不同的密码，您还可以更改 $certPassword 值。

## Number of years of certificate validity
$certYears = 1

## Certificate (PFX) password
$certPassword = '4~mt4G*8Qd@G'

.\Create-SelfSignedCertificate.ps1 -CommonName $appName `
-StartDate (Get-Date).AddDays(-1) `
-EndDate (Get-Date).AddYears($certYears) `
-Password (ConvertTo-SecureString $certPassword -AsPlainText -Force) `
-Force

当您在 PowerShell 中运行上面的代码时，将创建两个文件，如下面的演示所示。

下一步是将刚刚创建的证书上传到 Azure AD 应用程序。下面的代码将在工作目录中找到证书 (.CER) 文件，然后将其附加到 Azure AD 应用程序。无需修改代码，只需复制并在 PowerShell 中运行即可。

## Get the certificate file (.CER)
$CertificateFilePath = (Resolve-Path ".$($appName).cer").Path
## Create a new certificate object
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$cer.Import("$($CertificateFilePath)")
$bin = $cer.GetRawCertData()
$base64Value = [System.Convert]::ToBase64String($bin)
$bin = $cer.GetCertHash()
$base64Thumbprint = [System.Convert]::ToBase64String($bin)

## Upload and assign the certificate to application in AzureAD
$null = New-AzureADApplicationKeyCredential -ObjectId $myApp.ObjectID `
-CustomKeyIdentifier $base64Thumbprint `
-Type AsymmetricX509Cert -Usage Verify `
-Value $base64Value `
-StartDate ($cer.NotBefore) `
-EndDate ($cer.NotAfter)

当您在 PowerShell 中运行上述代码时，除非遇到错误，否则您不会看到任何输出。下面的demo展示了代码执行成功后的结果。

授予应用程序管理员同意

您的设置即将完成。下一步是全局管理员向您的 Azure AD 应用程序授予同意。此步骤可以由您自己或组织中的其他全局管理员执行。

全局管理员可以从Azure Active Directory 管理中心授予同意。但是，您也可以在 PowerShell 中生成同意 URL。要么将其提供给全局管理员，要么您可以自己使用它来授予同意。

同意 URL 遵循以下格式。

https://login.microsoftonline.com/{TenantID}/adminconsent?client_id={ApplicationID}

{TenantID} 值是 Office 365 租户的目录 ID 或经过验证的域。 {ApplicationID} 值是之前创建的 Azure AD 应用程序的 AppID。

下面的代码将根据上述值生成同意 URL。然后同意 URL 将显示在屏幕上并使用计算机的默认浏览器启动。

## Get the TenantID
$tenantID = (Get-AzureADTenantDetail).ObjectID

## Browse this URL
$consentURL = "https://login.microsoftonline.com/$tenantID/adminconsent?client_id=$($myApp.AppId)"

## Display the consent URL
$consentURL

## Launch the consent URL using the default browser
Start-Process $consentURL

请参阅下面的演示，了解在 PowerShell 中运行上述代码时会发生什么。

连接到 Exchange Online PowerShell

创建应用程序并分配权限和角色后，您现在需要上传并附加证书。您现在已准备好使用应用程序的证书凭据连接到 Exchange Online PowerShell。

有两种方式使用证书凭证；使用本地证书文件 (.pfx)，并使用当前用户的个人证书存储中安装的证书的指纹。

使用本地 PFX 证书进行身份验证

要使用本地证书连接到 Exchange Online PowerShell 进行身份验证，您必须拥有以下信息：

• Azure AD 租户的目录 ID 或经过验证的域。
• 您之前注册的应用程序的AppID。
• 自签名 PFX 证书的完整文件路径。
• 自签名 PFX 证书的密码。

接下来，更改 $tenantID、$appID、$CertificateFilePath 和 $pfxPassword 变量的值代码如下。根据需要更改变量的值后，复制代码并在 PowerShell 中运行它。

## set the tenant ID (directory ID or domain)
$tenantID = 'poshlab.ga'

## Set the Exo_V2_App app id
$appID = '3f76be04-5cf0-47f1-9df6-d05981a450fc'

## Set the certificate file path (.pfx)
$CertificateFilePath = 'C:\exo_v2_demo\Exo_V2_App.pfx'

## Get the PFX password
$pfxPassword = '4~mt4G*8Qd@G'

## Connect to Exchange Online
Connect-ExchangeOnline -CertificateFilePath $CertificateFilePath `
-CertificatePassword (ConvertTo-SecureString -String $pfxPassword -AsPlainText -Force) `
-AppID $appID `
-Organization $tenantID

下面的演示显示使用本地证书文件身份验证成功连接到 Exchange Online PowerShell。

如果你再仔细观察一下代码，就会发现一个明显的问题是 pfx 证书密码是可见的。您可以考虑使用某种秘密管理解决方案来存储证书凭据以提高安全性。

使用证书指纹进行身份验证

这种身份验证方法可以被认为比使用带有密码的本地证书更安全。在此方法中，您需要将证书导入到个人证书存储中。您只需使用指纹来识别使用哪个证书进行身份验证。

第一步是将 PFX 证书导入个人证书存储。请注意，您只需为当前用户执行此步骤一次。

# CODE TO IMPORT THE PFX CERTIFICATE INTO THE CURRENT PERSONAL CERTIFICATE STORE
## Set the certificate file path (.pfx)
$CertificateFilePath = 'C:\exo_v2_demo\Exo_V2_App.pfx'

## Get the PFX password
$mypwd = Get-Credential -UserName 'Enter password below' -Message 'Enter password below'

## Import the PFX certificate to the current user's personal certificate store.
Import-PfxCertificate -FilePath $CertificateFilePath -CertStoreLocation Cert:\CurrentUser\My -Password $mypwd.Password

下面的演示展示了如何将 PFX 证书导入到个人证书存储中。

如上所示，您将看到 PFX 导入过程的结果。请务必复制指纹的值，以便稍后快速参考。

导入证书后，您的脚本现在可以使用其指纹通过 Exchange Online PowerShell 进行身份验证。

编辑以下代码中的 $tenantID、$appID 和 $CertificateThumbPrint 以匹配您的正确值。然后，复制并在 PowerShell 中运行代码。

## set the tenant ID (directory ID or domain)
$tenantID = 'poshlab.ga'

## Set the Exo_V2_App app id
$appID = '3f76be04-5cf0-47f1-9df6-d05981a450fc'

## Set the certificate thumbprint
$CertificateThumbPrint = 'DED486B87C38CEA966EC71F8EE90BB3AAE694A74'

## Connect to Exchange Online
Connect-ExchangeOnline -CertificateThumbPrint $CertificateThumbPrint `
-AppID $appID `
-Organization $tenantID

在 PowerShell 中运行上面的代码将得到类似于下面演示的输出。

使用仅应用程序身份验证连接和运行 Exchange Online PowerShell 脚本

到目前为止，在本文中，您仅将代码复制并粘贴到 PowerShell 中。但现在您已经熟悉了仅应用程序身份验证的工作原理，您应该应用它来运行 PowerShell 脚本。

下面的脚本使用证书指纹连接到 Exchange Online PowerShell 进行身份验证。然后，一旦连接，脚本将获取所有可用的邮箱。该脚本保存在C:\exo_v2_demo\ListExoMailbox.ps1

## Clean up Exchange Online Session
Get-PSSession | Where-Object {$_.name -like "ExchangeOnline*"} | Remove-PSSession -ErrorAction SilentlyContinue

## set the tenant ID (directory ID or domain)
$tenantID = 'poshlab.ga'

## Set the Exo_V2_App app id
$appID = '3f76be04-5cf0-47f1-9df6-d05981a450fc'

## Set the certificate thumbprint
$CertificateThumbPrint = 'DED486B87C38CEA966EC71F8EE90BB3AAE694A74'

## Connect to Exchange Online
Connect-ExchangeOnline -CertificateThumbPrint $CertificateThumbPrint `
-AppID $appID `
-Organization $tenantID

## Get All Mailbox
Write-Output "Getting all mailboxes"
Get-Mailbox -ResultSize Unlimited | Format-Table Name,DisplayName

保存脚本后，在 PowerShell 中运行它。该脚本应在没有任何提示的情况下连接到 Exchange Online 并执行其功能。请参阅下面演示中显示的结果。

概括

EXO V2 PowerShell 模块的发布是一项值得欢迎的进展。了解 Microsoft 已决定取消通过 PowerShell 连接到 Exchange Online 的基本身份验证，并且拥有此新的仅应用程序身份验证功能允许管理员更新其现有脚本。

然而，实施仅 EXO V2 应用程序身份验证并非没有挑战。

• 使用本地证书文件仍然需要 PFX 密码。如果您可以实施凭据或秘密管理策略，您应该可以解决此密码暴露问题。
• 在个人商店使用证书相对更有信心。但该证书只能由当前用户访问。因此，如果您设置了计划任务以使用UserA的凭据运行脚本，则必须将证书导入到的个人证书存储中用户A。
• 证书有有效期。这意味着需要监视、续订证书并将其重新附加到 Azure AD 应用程序。否则，脚本将因身份验证失败而停止工作。

使用新的 EXO V2 PowerShell 模块的好处超过了这些挑战。

在本文中，您了解了为 Exchange Online V2 PowerShell 模块设置仅应用程序身份验证的分步过程。您还了解了如何使用自签名证书连接到 Exchange Online PowerShell。

现在，您不必处理 Exchange Online PowerShell MFA 提示，并在脚本中使用仅应用程序基于证书的身份验证。

如果您想更进一步，也许您想使用 Jenkins 或 Azure Automation 来测试您在本文中学到的内容。或者，也许构建您自己的 PowerShell 函数和模块

感谢您的阅读！

进一步阅读

• 如何通过 PowerShell 连接到 Exchange Online
• 如何：使用门户创建可以访问资源的 Azure AD 应用程序和服务主体
• 向租户范围内的管理员授予对申请的同意
• 再见 Import-CliXML - 在您的实验和演示中使用机密管理模块
• 如何使用计划任务自动进行文件传输
• 了解和构建 PowerShell 模块
• PowerShell函数介绍