使用 PowerShell SDK 连接到 Microsoft Graph

以安全且强大的方式连接到图表

更新日期：2023 年 8 月 1 日

在上一篇文章中，我讨论了使用适用于 PowerShell 的 Microsoft Graph SDK 中的 cmdlet 来替换 Azure AD 模块中的许可证管理 cmdlet，这些 cmdlet 将于 2022 年 6 月 30 日停用（更新：Microsoft 已将此日期移至 3 月2024 年）。事实证明，通过将几个 Azure AD cmdlet 替换为 Get-MgUser 和 Set-MgUserLicense 等 cmdlet 来转换它们并不是特别困难（如果是的话，我就无法做到这一点）。然而，在生产环境中使用的 PowerShell 组合中引入新模块总是会产生一些问题和担忧，其中最重要的是安全性。

在测试和生产环境中使用 Graph SDK cmdlet 的方法有正确和错误之分。简而言之，以交互方式运行 cmdlet 很简单，但可能会导致过度许可的服务主体 (应用程序) 出现问题。这与 Graph SDK 的连接方式及其使用的权限有关。让我们来看看为什么。

连接Graph SDK

使用 Graph SDK 的第一步是使用 Connect-MgGraph cmdlet 连接到 Graph。当您运行 Connect-MgGraph 来连接到 Graph 时，明智的做法是指定要连接的租户的标识符。

Connect-MgGraph -TenantId "828e1143-88e3-492b-bf82-24c4a47ada63"

如果您未指定租户，Connect-MgGraph 将选择您在会话期间登录的最后一个租户（可能不是您想要连接的租户）。当我连接到图表并发现所使用的数据属于我的开发租户时，我发现了这一点。我当时就注意到了，但其他人可能会在其他地方错过这一点，因此请养成与租户标识符连接的习惯。

会话将持续到您运行 Disconnect-MgGraph（见下文）为止，并且可以通过运行 Connect-MgGraph 在几天内多次重新启动。在幕后，Graph SDK 保留加密的令牌缓存，并将根据需要刷新令牌，以允许您使用 Graph 命令。

权限

成功连接后，会话将作为您的帐户登录。连接的权限范围来自在 Azure AD 中为 SDK 注册的服务主体（企业应用程序）。如果您以前从未使用 Graph SDK 登录过，该 SDK 会创建一个名为 Microsoft Graph Command Line Tools 的企业应用，其 AppId 为 14d82eec-204b-4c2f-b7e8-296a70dab67e 并请求一组有限的权限（图 1）。如果您是管理员，您可以代表组织授予这些权限的同意。为了减轻警惕的管理员的合理怀疑，如果服务主体显示为已验证，那就太好了，但目前情况并非如此。

Microsoft Graph PowerShell SDK 同意的权限由企业应用的服务主体持有。

收集新权限

当人们开始使用交互式客户端执行 Graph SDK 命令时，他们需要获得运行命令所需的权限的同意。例如，要使用 Get-MgUser cmdlet 检索一组 Azure AD 帐户，用户需要读取目录信息的权限，因此他们可能会使用 Scope 来请求权限> 连接时参数如下：

$RequiredScopes = @("Directory.AccessAsUser.All", "Directory.ReadWrite.All")
Connect-MgGraph -Scopes $RequiredScopes

连接到包含企业应用程序未持有的权限的范围会导致 Azure AD 提示您同意未从服务主体继承的权限（图 2）。

与使用图形 API 的其他应用程序一样，管理员代表组织同意所请求的权限。这会向服务主体持有的集合添加额外的权限。如果管理员未授予同意，则请求的权限可用于会话（取决于登录帐户持有的管理角色），但不加入服务主体持有的权限集。

随着时间的推移，SDK 服务主体所持有的权限将是最初同意时授予的权限以及人们使用交互式客户端时随后授予的任何其他权限。换句话说，服务主体随着时间的推移收集聚合权限。因此，不建议以交互方式使用 Graph SDK cmdlet，因为如果这样做，随着时间的推移，服务主体很可能会变得过度许可，从而成为安全风险。这是 Cloud App Security 的应用程序治理（或在本文中解释的本土解决方案中）强调的问题类型。此外，您应该注意分配了高优先级权限的应用程序，因为它们可能会被攻击者植入或利用。

对于过度许可的服务主体，唯一的解决方案是删除并重新创建，此时管理员可以向新服务主体授予有限权限的同意。以下是如何使用 Graph SDK cmdlet 删除服务主体（自然）：

$Sp = Get-MgServicePrincipal -Filter "AppId eq '14d82eec-204b-4c2f-b7e8-296a70dab67e'"
Remove-MgServicePrincipal -ServicePrincipalId $Sp.Id

连接到 Beta 配置文件

在某些情况下，您需要使用 beta 配置文件来访问某些命令和数据。这相当于在发出 Graph API 查询时指定 beta 端点。要选择 beta 配置文件，请运行 Select-MgProfile cmdlet：

Select-MgProfile beta

更新：Microsoft Graph PowerShell SDK V2.0 不再需要 Select-MgProfile cmdlet。相反，测试版 cmdlet 位于单独的模块中。

报告您的连接

要检查您是否已连接到具有正确配置文件和权限的正确租户，我们可以使用 Get-MgOrganization cmdlet 提取有关租户的信息、与 Get-MgContext 的当前连接 cmdlet，以及与 Get-MgProfile cmdlet 一起使用的配置文件，并显示一些有用的信息：

$Details = Get-MgContext
$Scopes = $Details | Select -ExpandProperty Scopes
$Scopes = $Scopes -Join ", "
$OrgName = (Get-MgOrganization).DisplayName
CLS
Write-Host "Microsoft Graph Connection Information"
Write-Host "--------------------------------------"
Write-Host " "
Write-Host ("Connected to Tenant {0} ({1}) as account {2}" -f $Details.TenantId, $OrgName, $Details.Account)
Write-Host "+-------------------------------------------------------------------------------------------------------------------+"
Write-Host ("Profile set as {0}. The following permission scope is defined: {1}" -f $ProfileName, $Scopes)
Write-Host ""

Microsoft Graph Connection Information
--------------------------------------

Connected to Tenant a662313f-14fc-43a2-9a7a-d2e27f4f3475 (Office 365 for IT Pros) as account [email protected]
+-------------------------------------------------------------------------------------------------+
The following scopes are defined: Directory.AccessAsUser.All, Directory.ReadWrite.All, openid, profile, User.Read, email, Group.Read.All, Group.ReadWrite.All 

上面列出的权限包括从服务主体继承的权限以及用户为会话请求的任何其他权限。

完成后断开连接

当您完成与图表的交互后，请记得通过运行 Disconnect-MgGraph 来关闭会话，以将会话从图表中注销。断开会话连接会删除加密的内容令牌缓存并防止会话重新初始化。

Disconnect-MgGraph

仅适用于生产用途的应用程序访问

上面的描述涵盖了交互式会话。这是了解 Graph SDK cmdlet 和调试脚本以准备操作使用的好方法。但是，当您以交互方式运行 SDK cmdlet 时，您只能委派权限。换句话说，您可以访问可通过 Microsoft 365 应用进行交互的项目，但无法访问其他用户拥有的项目。例如，您可以阅读您邮箱中的邮件，但不能阅读其他邮箱中的邮件。如果要使用应用程序权限运行 SDK，可以使用应用程序或在 Azure 自动化中（使用 RunAs 帐户或托管标识）执行此操作。

由于同意和服务主体的问题，Microsoft 建议操作脚本使用注册的 Azure AD 应用程序以及基于证书的身份验证（仅限应用程序访问）或托管标识。您当然可以使用交互式客户端编写和测试脚本，但是一旦代码完成，就可以使用具有严格范围权限集的自己的应用程序来运行它。此方法意味着您可以将分配给应用程序的权限限制为仅由脚本完成的处理所需的权限集，并将可以使用该应用程序的用户限制为选定的一组帐户。使用具有范围权限的单独应用程序的缺点是，随着时间的推移，您可能会在 Azure AD 中积累许多需要管理的已注册应用程序。

另一种方法是使用具有托管标识的 Azure 自动化来运行使用 SDK cmdlet 的脚本。请参阅这篇文章了解更多信息。

微软需要解决的一些问题

拥有一个不断努力收集权限的服务主体似乎不是一个好主意。事实上，这是一个糟糕的想法。 Microsoft 需要提出一种更好的方法，允许管理员以交互方式运行 Graph SDK cmdlet，而不会产生安全问题。在运行 Disconnect-MgGraph 时删除安全主体是一种将权限归零的方法，但这是一个糟糕的解决方案。考虑到当前的威胁形势，允许人们对用户名和密码进行硬编码或在脚本中使用应用程序机密来验证对图的访问也不是一个方向。

事实上，租户管理员将忘记权限累积问题，除非他们检查服务主体。这很悲伤，但却是事实，而且是由于其他工作的需要。人们不会运行 Disconnect-MgGraph 的原因与忽略 Disconnect-MicrosoftTeams 和 Disconnect-ExchangeOnline 等 cmdlet 的原因相同。

Graph SDK 是一个极好的主意，因为它将 PowerShell 用户与使用 Graph API 涉及的许多复杂性隔离开来。这仍然是一项正在进行的工作，但如果微软想让 Graph SDK 成为租户管理员的首选工具，他们需要解决权限问题。很快（在弃用截止日期之前！）