连接到 Microsoft Graph PowerShell

安装 Microsoft Graph 模块后，您可以连接到 Microsoft Graph PowerShell。连接到 Microsoft Graph PowerShell 的方法有多种。在本文中，我们将向您展示如何使用交互模式、自签名证书和客户端密钥连接到 Microsoft Graph。

微软图谱

Azure Active Directory Graph API 自 2023 年 6 月 30 日起已弃用，因此现在必须将应用程序迁移到 Microsoft Graph。连接到 Microsoft Graph 后，您可以访问 Azure AD 服务和 Microsoft 365 服务。

Microsoft Graph 具有 Azure AD Graph 中提供的所有功能以及身份保护和身份验证方法等新 API。

安装 Microsoft Graph PowerShell 模块

首先，您需要安装 Microsoft Graph PowerShell 模块。 Microsoft Graph PowerShell SDK 包含 2 个模块，您将分别安装：

• Microsoft.Graph PowerShell 模块
• Microsoft.Graph.Beta PowerShell 模块

我们建议您更新到最新版本，因为某些 cmdlet 将无法工作。

注意：您需要安装 Microsoft Graph PowerShell 模块 v2.x 才能连接 Microsoft Graph 来运行自动化脚本。

检查 Microsoft Graph PowerShell 模块

您可以验证是否已安装 Microsoft Graph PowerShell SDK 并查看模块正在运行的版本。

运行以下 PowerShell 命令。

Get-InstalledModule Microsoft.Graph | ft -AutoSize
Get-InstalledModule Microsoft.Graph.Beta | ft -AutoSize

输出显示您安装的版本。

PS C:\> Get-InstalledModule Microsoft.Graph | ft -AutoSize
Get-InstalledModule Microsoft.Graph.Beta | ft -AutoSize

Version Name            Repository Description                      
------- ----            ---------- -----------                      
2.7.0   Microsoft.Graph PSGallery  Microsoft Graph PowerShell module


Version Name                 Repository Description                      
------- ----                 ---------- -----------                      
2.7.0   Microsoft.Graph.Beta PSGallery  Microsoft Graph PowerShell module

更新 Microsoft Graph PowerShell 模块

您可以始终使 Microsoft Graph PowerShell SDK 保持最新。

运行以下命令来更新 Microsoft Graph 和 Microsoft Graph Beta 模块。

Update-Module Microsoft.Graph -Force
Update-Module Microsoft.Graph.Beta -Force

将 Microsoft Graph PowerShell 模块安装到最新版本后，您可以开始连接。

连接到 Microsoft Graph PowerShell 的三种方法

我们将向您展示三种连接 Microsoft Graph PowerShell 的方法：

1. 交互模式（委托访问）
2. 基于证书的身份验证 (CBA)
3. 客户端秘密（密码）

第一种方法是最简单的，因为您只需要使用 PowerShell 连接。其他两种方法类似，因为它需要在 Azure AD 中创建新应用程序。方法 2 和 3 之间的区别在于，有两种方法可以对 Azure Active Directory 中新创建的应用程序进行身份验证。

我们将向您展示两种方法，但建议为您的应用程序添加证书 (CBA) 而不是客户端密钥，因为它们不那么安全。

1.以交互方式连接MgGraph

第一种方法是使用 PowerShell 连接到 Microsoft Graph API 的最快、最简单的方法。

1. 以管理员身份打开 PowerShell 并运行以下命令。

Connect-MgGraph

1. 使用您的管理员凭据登录。

1. 如果您启用了 MFA，您将收到以短信形式发送或发送到手机上的身份验证应用程序的验证码。如果您的 MFA 被禁用，您将无法在此处执行任何操作。

现在您必须返回 PowerShell 窗口，您将在其中获得以下输出。

PS C:\> Connect-MgGraph
Welcome To Microsoft Graph!

注意：您无法运行自动化脚本，但它可用于测试或运行脚本。

如果您想运行自动化任务，您应该使用下一个方法。

2. 使用基于证书的身份验证连接 MgGraph

在我们使用 PowerShell 连接到 Microsoft Graph 之前，您需要在 Azure AD 中注册应用程序并分配 API 权限。然后我们将为应用程序创建一个自签名证书。

在 Azure AD 中注册新应用程序

首先，您需要注册一个应用程序，您将在其中获得应用程序（客户端）ID 和目录（租户）ID。

所需时间：10 分钟

如何在 Microsoft Entra 管理中心注册新应用程序：

1. 登录 Microsoft Entra 管理中心。

   使用您的管理员凭据登录

2. 转到 Azure Active Directory。

   单击“应用程序”>“应用程序”注册
   点击新注册
   

   

3. 注册应用程序。

   为您的应用程序命名 MSGraph 机器人
   选择仅此组织目录中的帐户（- 单个租户）
   点击注册
   

   

4. 已成功创建应用程序 MSGraph 机器人。

   您将被重定向到 MSGraph 机器人概览页面
   复制应用程序 ID 和目录 ID
   

   

您需要复制以下值并将其粘贴到记事本中，因为稍后连接到 Microsoft Graph 时需要它们：

• 应用程序（客户端）ID
• 目录（租户）ID

分配API权限

您必须为您创建的 MSGraph 机器人应用程序分配 API 权限。

1. 点击API权限
2. 点击添加权限

1. 在Microsoft API选项卡下
2. 单击Microsoft Graph

1. 点击应用程序权限
2. 搜索User.Read.All
3. 选择用户 > User.Read.All
4. 点击添加权限

1. 点击授予 a-d 管理员同意
2. 单击是

出现绿色复选标记，表明您已成功授予管理员同意！

创建自签名证书

创建新应用程序后，可以使用自签名证书将 .pfx 文件和 .cer 文件上传到 Azure AD。

首先，您需要生成一个自签名证书。最好在要运行无人值守 PowerShell 脚本的同一台计算机上制作证书。

以管理员身份使用 Windows PowerShell 登录任何 Windows 服务器或桌面。

注意：自签名证书默认有效期为一年

在我们的示例中，我们将为自签名证书添加 5 年以避免每年续订。

使用以下 PowerShell cmdlet 创建新的自签名证书。

$mycert = New-SelfSignedCertificate -DnsName "a-d.site" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(5) -KeySpec KeyExchange -FriendlyName "MSGraph Bot"

证书现已存储，要查看指纹，请使用以下 PowerShell cmdlet。

$mycert | Select-Object -Property Subject,Thumbprint,NotBefore,NotAfter

复制指纹并将其粘贴到记事本中。稍后当您使用 CBA 连接到 Microsoft Graph PowerShell 时将需要它。

PS C:\> $mycert | Select-Object -Property Subject,Thumbprint,NotBefore,NotAfter

Subject         Thumbprint                               NotBefore             NotAfter             
-------         ----------                               ---------             --------             
CN=a-d.site 03D55A7B5A29D571BDEB21F1079541F130F93B26 7/19/2023 11:49:38 AM 7/19/2028 11:59:38 AM

使用 PowerShell 导出到 .cer 文件

我们想要创建一个.cer 文件以便稍后上传到 Azure AD 应用程序中。使用 .cer 文件，您只能从生成自签名证书的计算机连接到 Microsoft Graph。

创建一个名为 temp 的文件夹，将其保存在 C:\temp 中。

使用以下 PowerShell cmdlet 将证书导出到 .cer 文件。

$mycert | Export-Certificate -FilePath "C:\temp\MSGraphBot.cer"

您将在 PowerShell 中看到以下输出。

PS C:\> $mycert | Export-Certificate -FilePath "C:\temp\MSGraphBot.cer"


    Directory: C:\temp


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        7/19/2023  12:00 PM            805 MSGraphBot.cer

您可以在计算机上的 C:\temp 中找到 .cer 文件。

导出到 .pfx 文件

我们还将创建一个 .pfx 文件，以便您可以从任何计算机连接到 Microsoft Graph。您可以将 .pfx 文件复制或发送给某人，以便将其安装在另一台计算机上，因为将在身份验证过程中检索 .pfx 文件。

$mycert | Export-PfxCertificate -FilePath "C:\temp\MSGraphBot.pfx" -Password $(ConvertTo-SecureString -String "P@ssw0Rd1234" -AsPlainText -Force)

请参阅下面的输出。

PS C:\> $mycert | Export-PfxCertificate -FilePath "C:\temp\MSGraphBot.pfx" -Password $(ConvertTo-SecureString -String "P@ssw0Rd1234" -AsPlainText -Force)


    Directory: C:\temp


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        7/19/2023  12:02 PM           2709 MSGraphBot.pfx

您可以在计算机上的 C:\temp 中找到 .pfx 文件。

将证书上传到应用程序

现在我们需要上传您之前创建的自签名证书。

来自 MSGraph 机器人 概述：

1. 点击证书和机密
2. 选择证书
3. 点击上传证书
4. 单击浏览图标在 C:\temp 中搜索并选择 MSGraphBot.cer 文件
5. 添加描述MSGraph机器人
6. 点击添加

该证书将显示在带有指纹的列表中。

注意：始终确保其具有与您之前创建的证书指纹相同的证书指纹。

使用 CBA 连接到 Microsoft Graph

键入以下信息以使用基于证书的身份验证连接到 Microsoft Graph PowerShell：

• 在第 1 行中填写应用程序 ID
• 在第 2 行中填写租户 ID
• 在第 3 行填写证书指纹

运行以下 PowerShell 脚本以使用 CBA 连接到 Microsoft Graph。

# Configuration
$ClientId = "9e2c8889-527c-4ce9-9da8-6b4ce9abe3b7"
$TenantId = "a2ff010e-0e03-4c56-8863-2ae7f07876dd"
$CertificateThumbprint = "03D55A7B5A29D571BDEB21F1079541F130F93B26"

# Connect to Microsoft Graph with CBA
Connect-MgGraph -ClientId $ClientId -TenantId $TenantId -CertificateThumbprint $CertificateThumbprint

您已连接到 Microsoft Graph。一个很好的验证方法是运行以下 cmdlet。

Get-MgUser

3. 将 MgGraph 与 Client Secret 应用程序连接

在最后一种方法中，我们将向您展示如何为新创建的应用程序创建客户端密钥。

在 Azure AD 中注册新应用程序

请参阅上述步骤在 Azure 中注册新应用程序。在我们的示例中，我们将使用之前创建的相同应用程序。

分配API权限

请参阅上述步骤将 API 权限分配给 Azure 应用程序。在我们的示例中，我们已经为之前创建的应用程序分配了 API 权限。

创建客户端机密

转到 Azure AD 中的 MSGraph 机器人应用程序概述页面。

要在 Microsoft Entra 门户中为您的应用程序创建客户端密钥，请按照下列步骤操作：

1. 单击证书和机密
2. 单击客户端密钥 > 新客户端密钥
3. 输入描述
4. 选择到期日期
5. 点击添加

注意：客户端密钥的有效期最长为 24 个月（2 年）。您可以使用 PowerShell 在 Azure AD 中创建无限的客户端密钥。

1. 复制客户端密钥值并保存

注意： 除非在创建后立即查看客户端密钥值，否则无法查看。请记住在离开页面之前保存创建的密码。

使用客户端密钥连接到 Microsoft Graph

您需要更改以下参数值才能使用客户端密钥连接到 MS Graph：

• 在第 2 行中输入应用程序客户端 ID
• 在第 3 行中输入目录租户 ID
• 在第 4 行中输入客户端密钥值

运行以下 PowerShell 脚本。

# Configuration
$ClientId = "9e2c8889-527c-4ce9-9da8-6b4ce9abe3b7"
$TenantId = "a2ff010e-0e03-4c56-8863-2ae7f07876dd"
$ClientSecret = "ZZj8Q~pHUbxG1uX5bNmuM5XV-rQb20tiWHEEkbsO"

# Convert the client secret to a secure string
$ClientSecretPass = ConvertTo-SecureString -String $ClientSecret -AsPlainText -Force

# Create a credential object using the client ID and secure string
$ClientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $ClientId, $ClientSecretPass

# Connect to Microsoft Graph with Client Secret
Connect-MgGraph -TenantId $TenantId -ClientSecretCredential $ClientSecretCredential

您已连接到 Microsoft Graph。一个很好的验证方法是运行以下 cmdlet。

Get-MgUser

就是这样！您已成功连接到 Microsoft Graph PowerShell！

阅读更多内容：配置基于证书的身份验证以运行自动化脚本 »

结论

您了解了如何使用自签名证书、客户端密钥和交互模式连接到 Microsoft Graph PowerShell。如果您使用客户端密钥或 CBA 连接，请记住将 MS Graph 模块更新到最新版本，创建应用程序并分配 API 权限。使用 CBA，运行自动化脚本不再涉及用户交互、用户名、密码或 MFA。

您喜欢这篇文章吗？您可能还喜欢在 Azure 中使用基于组的许可分配 Microsoft 365 许可证。不要忘记关注我们并分享这篇文章。