如何使用 Connect-MgGraph - 所有选项

PowerShell 中的 Microsoft Graph 模块允许您与不同的 Microsoft 365 服务进行交互。但要使用该模块，您首先需要使用 Connect-MgGraph cmdlet 连接到 Microsoft Graph。

在对 Microsoft Graph 连接进行身份验证时，有不同的选项，从交互式登录到基于证书的托管身份。后者非常适合后台操作。

在本文中，我们将了解如何使用 Connect-MgGraph、不同的范围和身份验证方法。

安装 Microsoft Graph 模块

在我们了解如何连接到 Microsoft Graph 之前，我们首先需要确保您已在 PowerShell 中安装了该模块。该模块实际上称为 Microsoft Graph PowerShell SDK。

建议使用 PowerShell 7 for Microsoft Graph，但您也可以在旧版 PowerShell 5.1 中安装和使用该模块。如果您想了解如何安装或升级 PowerShell，请务必阅读本文。

您可以使用以下命令检查是否安装了该模块：

Get-InstalledModule Microsoft.Graph

要安装该模块，我们将使用 Install-Module cmdlet。最简单的方法是仅为当前用户安装它，但您也可以为所有用户安装它：

Install-Module Microsoft.Graph -Scope CurrentUser

如果您想了解有关安装 Microsoft Graph 的更多信息，例如如何仅安装特定模块或测试版，请务必阅读本文。

连接 MgGraph 方法

Microsoft Graph 有不同的方法可以用来进行身份验证，但它们都可以分为两种类型的身份验证：

• 委派访问 - 代表登录用户执行命令。您将需要使用范围来定义 cmdlet 可以执行哪些操作。

• 仅应用程序访问 - 身份验证基于访问令牌（形式），允许 Microsoft Graph 在没有登录用户的情况下访问资源。权限（范围）在访问令牌中定义

对于委托访问，我们可以使用以下方法：

• 交互式身份验证 - 您将收到使用您自己的帐户登录的提示。

• 设备代码 - 用于在另一台设备上进行身份验证。

• 自己的访问令牌 - 使用您自己的访问令牌进行身份验证。

• 自定义应用程序 - 允许您使用 Azure AD 应用程序并将登录限制为指定的用户或组。

您还可以使用不同的方法进行仅限应用程序访问：

• 基于证书 - 允许您使用自签名证书

• 托管身份 - 用于 Azure Runbook 等。

• 客户端密钥 - 使用 Azure 应用程序中的客户端密钥。非常适合后台工作。

范围

通过委派访问连接到 Microsoft Graph 时，您需要定义要授予权限的范围。另外，使用仅应用程序方法时，您需要为 Graph 设置正确的 API 权限。但您如何知道您需要哪些范围呢？

有两种方法可以查找 cmdlet 需要哪些权限，您可以查看文档或使用 cmdlet Find-MgGraphCommand。我们以 cmdlet Get-MgUserAuthenticationMethod 为例。

如果我们查看文档，您通常会在描述中找到权限表。当权限未列出时，我们可以使用 Find-MgGraphCommand cmdlet 或 Find-MgGraphPermission cmdlet

Find-MgGraphCommand -Command "Get-MgUserAuthenticationMethod" | select -ExpandProperty Permissions | Select -Unique name

# Or 
Find-MgGraphPermission AuthenticationMethod

另一种选择是使用图形浏览器，请在本文中阅读有关该方法的更多信息。

委托访问

如前所述，当你想要在本地运行脚本或只想从控制台与 Microsoft Graph 交互时，将使用委派访问权限。通过委派访问，我们需要定义连接 Microsoft Graph 时要使用的范围。

交互式认证

最常用的身份验证方法是交互式身份验证。这是默认方法，因此我们只需要定义要授予权限的范围。例如，要获取所有用户和组，您需要使用 User.Read.All 和 Group.Read.All 作用域：

# Connect to MgGraph with user and group read permissions
# and suppress the welcome message

Connect-MgGraph -Scopes "User.Read.All", "Group.Read.All" -NoWelcome

运行该命令时，将打开一个新的浏览器选项卡，允许您使用 Microsoft 365 凭据登录。

设备代码

当您无法在运行 Connect-MgGraph 命令的设备上进行身份验证时，也可以使用设备代码流。这允许您通过打开网页 https://microsoft.com/devicelogin 在另一台计算机上完成身份验证过程。

Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All" -UseDeviceAuthentication

访问令牌

访问令牌方法允许你使用自己的访问令牌向 Microsoft Graph 进行身份验证。例如，可以通过登录 Microsoft Graph Explorer 页面来获取此令牌。

然后，您可以从访问令牌选项卡复制访问令牌。复制令牌并将其粘贴到 Connect-MgGraph cmdlet 中：

Connect-MgGraph -Accesstoken <paste-your-token-here>

自定义 Azure 应用程序

委托访问的最后一个选项是使用自定义 Azure 应用程序。当您需要限制特定用户或组的访问权限时，此方法非常有用。

1. 打开 Microsoft Entra > 应用程序注册

2. 创建新注册

3. 帐户类型 - 仅此组织目录中的帐户（单个租户）

4. 重定向 URI - 公共客户端/本机 > http://localhost

5. 注册

6. 打开企业应用程序 > 选择您的新应用程序

7. 单击属性 - 启用所需的分配

8. 打开用户和组 - 添加允许使用该应用程序的用户或组。

在脚本中使用以下连接方法连接到 Microsoft Graph：

Connect-MgGraph -ClientId <your-app-id> -TenantId <tenant-id>

仅应用程序访问

当您想要在本地计算机或服务器上将 PowerShell 脚本作为计划任务运行时，您将需要使用仅限应用程序的访问权限。这允许您创建应用程序并仅分配脚本所需的权限。

基于证书

对本地计划的 PowerShell 脚本进行身份验证的最佳方法是使用基于证书的身份验证方法。此方法使用我们可以在 PowerShell 中创建的自签名证书。

第 1 步 - 创建自签名证书

第一步是创建自签名证书。您可以在本地计算机上创建证书，但请确保已将其安装在要安排脚本的计算机的受信任存储中。

为了创建证书，我们将使用 New-SelfSigendCertificate cmdlet。指定有意义的名称和主题，以便您知道证书的用途。证书默认有效期为一年：

$cert = New-SelfSignedCertificate -FriendlyName "PSMsGraph" -Subject "Test Cert PowerShell MsGraph" -CertStoreLocation "Cert:\CurrentUser\My"

下一步是导出证书，以便我们可以将其上传到 Azure AD 应用程序。请注意文件路径中的文件名：

Export-Certificate -Cert $cert -FilePath "c:\temp\PSMsGraph.cer"

步骤 2 - 创建 Azure AD 应用程序

创建证书后，我们现在可以创建 Azure AD 应用程序。在这里我们将上传证书并设置所需的权限。该权限需要管理员同意，因此请确保您拥有正确的权限。

1. 打开 Microsoft Entra 管理中心

2. 展开应用程序并单击应用程序注册

3. 选择新注册

1. 输入应用程序的名称

2. 选择仅此组织目录中的帐户

3. 点击注册（我们不需要输入重定向 URI）

步骤 3 - 配置权限

创建应用程序后，我们现在需要配置脚本所需的 Microsoft Graph 权限。权限与范围相同，因此如果您想知道要设置哪个权限，则可以使用相同的方法查找范围。

1. 打开API权限

2. 点击添加权限

3. 选择Microsoft Graph

1. 选择应用程序权限

2. 选择您要添加的权限

3. 点击的高级管理员同意

第 4 步 - 上传证书

设置权限后，我们现在可以上传证书。该证书用于验证连接。

1. 单击证书和机密

2. 选择证书并点击上传证书

3. 上传我们之前导出的 .cer 文件

第 5 步 - 将 MgGraph 与证书连接

我们现在已经创建了使用证书连接到 MgGraph 所需的应用程序和证书。有 3 种方法可以使用证书连接到 MgGraph，但对于所有方法，我们都需要 Azure 应用程序的 ClientId 和租户 ID。

您可以在Microsoft Entra 管理中心的应用程序概述中找到这两个内容 > 应用程序注册 >

使用证书连接到 MgGraph 的第一种方法是使用证书指纹。

Connect-MgGraph -ClientId "d24d7358-12ab-2356-aabbn-asd131asb" -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -CertificateThumbprint "2BF6BDD0286EF8A0AS2341NLSDH1L234C"

您可以在应用程序证书下的 Microsoft Entra > 应用程序注册中找到证书指纹。或者您可以使用以下 PowerShell 命令来查看所有自签名证书：

Get-ChildItem Cert:\CurrentUser\My

# Result
Thumbprint                                Subject
----------                                -------
2BF6BDD0286EF8A0AS2341NLSDH1L234C         CN=Test Cert PowerShell MsGraph

也可以使用证书使用者名称进行连接，但您需要将 cn= 添加到使用者名称中，就像上面的命令列出的那样。

Connect-MgGraph -ClientId "d24d7358-12ab-2356-aabbn-asd131asb" -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -CertificateSubjectName "CN=Test Cert PowerShell MsGraph"

最后一个选项是在 connect-mggraph cmdlet 中使用证书：

$Cert = Get-ChildItem Cert:\LocalMachine\My$CertThumbprint
Connect-MgGraph -ClientId "d24d7358-12ab-2356-aabbn-asd131asb" -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -Certificate $Cert

托管身份

在 Azure Runbook 内使用 Microsoft Graph 连接时，可以使用托管标识方法进行身份验证。这将从 Azure 资源获取访问令牌，这是在 Runbook 中使用 MgGraph 的最便捷方法。

您需要确保已为您的自动化帐户启用系统分配的托管标识，请阅读本文中的更多信息。

要使用托管身份连接到 MgGraph，您只需指定 -Identity 参数即可：

Connect-MgGraph -Identity

客户秘密

通过仅应用程序访问连接到 Microsoft Graph 的最后一个选项是使用客户端机密凭据。对于此方法，您还需要创建一个 Azure AD 应用程序，只需按照基于证书的身份验证方法中的步骤 2 和 3 进行操作即可。

1. 在 Azure AD 应用中，打开证书和机密

2. 单击客户端密钥 > 新客户端密钥

3. 输入描述并点击添加

1. 复制值（您只能在创建后立即查看该值）

2. 使用 Get-Credential 创建凭证对象并连接到 MgGraph：

# Credential = Application Client ID
$ClientSecretCredential = Get-Credential -Credential "d24d7358-12ab-2356-aabbn-asd131asb"

# Connect to MgGraph using the client secret
Connect-MgGraph -TenantId "11e55098-12ab-2356-aabbn-asd34fgdsav2" -ClientSecretCredential $ClientSecretCredential

这里需要注意的是，用于创建凭证对象的客户端 ID 是应用程序客户端 ID（不是秘密 ID！）

包起来

如您所见，有多种方法可以在 PowerShell 中连接到 Microsoft Graph。在控制台本地工作时，交互式方法是最方便使用的方法。但是，当您想要安排脚本时，您将需要使用证书或托管身份方法。

确保为连接定义正确的范围/权限，否则，您将无法使用所需的 cmdlet。

我希望这篇文章对您有所帮助，如果您有任何疑问，请在下面发表评论。