Entra PowerShell 模块预览版推出

基于 Microsoft Graph 构建的新 Entra PowerShell 模块预览

2024 年 6 月 27 日，微软宣布推出 Microsoft Entra PowerShell 模块的公共预览版。新模块旨在帮助那些仍然拥有运行来自 Microsoft 于 2024 年 3 月 30 日弃用的 AzureAD 和 AzureAD Preview 模块的 cmdlet 的客户进行迁移。Microsoft 表示，这些模块将一直运行到 2025 年 3 月 30 日，然后将被删除。退休了，显然时间已经不多了。

话又说回来，自从 Microsoft 于 2020 年 6 月首次宣布打算放弃 Azure Graph 以采用 Microsoft Graph 作为 Azure AD (Entra ID) PowerShell 的基础以来，这些模块的时间已经不多了。我想这需要一些组织迁移时间较长。

微软表示新模块“质量很高”。我们希望如此，因为 Entra PowerShell 模块是建立在 Microsoft Graph PowerShell SDK 之上的，而 Microsoft Graph PowerShell SDK 最近有过令人遗憾的质量故障历史。

为什么有两个模块？

几个月前，当我第一次听说 Entra PowerShell 模块时，我最初的反应是该模块的存在会让客户感到困惑。在过去的几年里，我们一直在说服人们接受 Microsoft Graph 的智慧。即使在此过程中遇到了一些障碍，我们仍然鼓励人们重写脚本并使用 Microsoft Graph PowerShell SDK cmdlet 替换旧的 AzureAD 和 MSOL cmdlet。

让我澄清这一点：如果您已采纳我们的建议并迁移到 Microsoft Graph PowerShell SDK，那么您无需再做任何事情。 Entra PowerShell 模块适用于尚未从旧 AzureAD 模块过渡的组织。该解决方案允许旧的 cmdlet“以最少的修改”运行。这意味着 Entra PowerShell 模块包含 EntraAzureADAlias cmdlet。在会话中使用时，EntraAzureADAlias cmdlet 会启用常见 AzureAD cmdlet 的别名，例如 Get-AzureADUser 和 Get-AzureADGroup。

提供一个别名来将旧的 AzureAD cmdlet 名称转换为 Entra cmdlet 名称很好，而且大部分情况下都有效。不支持来自 Microsoft Services Online (MSOL) 模块的 cmdlet，例如 Get-MsolUser。

尽管别名允许使用 AzureAD cmdlet 运行命令，但 Entra 模块并不是迁移的灵丹妙药。并非所有命令都可以在没有干预的情况下运行，并且由于图形身份验证和权限是该模块的基础，因此需要做大量工作来确保脚本顺利运行。

安装 Entra PowerShell 模块

Entra PowerShell 模块依赖于随 Microsoft Graph PowerShell SDK 分发的许多模块，包括处理连接的 Microsoft.Graph.Authentication 模块。在尝试安装 Entra 模块之前，请启动新的 PowerShell 会话，以消除与 Entra 模块一起分发的 Graph 模块之间发生冲突的可能性。然后从 PowerShell 库安装 V1.0 和 beta 模块：

Install-Module Microsoft.Graph.Entra -AllowPrerelease -Repository PSGallery -Force
Install-Module Microsoft.Graph.Entra.Beta -AllowPrerelease -Repository PSGallery -Force

Microsoft Graph PowerShell SDK 在其 V2.0 版本中分为 V1.0（生产）和 beta 模块，这就是 Entra 模块使用相同结构的原因。如果您打算使用 beta cmdlet，则只需安装 beta 模块。问题是很难预测何时会出现这种需求，因此安装两者更安全。

如果 PowerShell 安装程序抱怨它无法安装模块，因为系统上已存在某些 cmdlet，请添加 AllowClobber 参数（这是我必须做的）。

连接 Entra PowerShell 模块

要启动 Entra PowerShell 会话，请使用 Connect-Entra cmdlet，其方式与 Microsoft Graph PowerShell SDK 的 Connect-MgGraph cmdlet 函数相同。事实证明，Connect-Entra 是 Connect-MgGraph 的别名，其存在纯粹是为了让新模块看起来有自己的连接 cmdlet：

Import-Module Microsoft.Graph.Entra
Connect-Entra -NoWelcome -Scopes User.Read.All

立刻，对 Graph API 和权限的依赖就显而易见了。在该公告的常见问题解答中，微软表示 Entra PowerShell 模块不是“预先同意的应用”或“预先授权”。当某人运行 Connect-AzureAD cmdlet 来创建与 AzureAD 模块的会话时，与其帐户持有的任何角色关联的权限都可用。图表的情况非常不同。

例如，管理员无需进一步的权限即可运行 Get-AzureADGroup 或 Get-AzureADUser cmdlet 来管理租户的用户或组。但通过 Graph API 执行的相同操作需要明确同意 User.Read.All 或 Group.Read.All 等权限。可以通过寻求特定范围的同意来获得权限登录交互式会话时或通过登录用户担任的管理角色时。但是，由于交互式会话使用委派权限，因此某些只能通过应用程序（仅限应用程序）权限访问的数据将仍然无法访问。

在将 AzureAD cmdlet 迁移到 Entra cmdlet 的上下文中，应用程序权限不应该成为问题，因为大多数使用交互式 Entra 会话的人都是管理员，而且 AzureAD cmdlet 不会与需要应用程序权限的 Microsoft 365 数据（例如邮箱或网站）进行交互。如果要将应用程序权限与 Entra PowerShell 模块一起使用，请创建 Entra 应用程序注册，为应用程序分配必要的应用程序权限，并使用加载到应用程序中的证书或证书指纹进行身份验证。

运行 AzureAD Cmdlet

我没有任何基于现在正在使用的 AzureAD 模块的脚本。一切都已转换为 Microsoft Graph PowerShell SDK。这意味着我必须回顾一些旧文章来查找测试用例，看看 Entra PowerShell 模块与旧代码的复制效果如何。下面是两个例子：

查找租户中的所有成员帐户：

Enable-EntraAzureADAlias
$Users = Get-AzureADUser -All $True -Filter "Usertype eq 'Member'"
Get-EntraUser: A positional parameter cannot be found that accepts argument 'True'.

Microsoft 声称 Entra 模块与 AzureAD cmdlet 的兼容性“超过 98%”。我想我很不幸地发现我尝试的第一个 cmdlet 存在问题！据 Microsoft 联系人透露，开发团队特意决定将 All 参数设置为开关参数而不是布尔值，以纠正他们认为的不良模式。这种立场是完全有道理的，但它会导致一些脚本失败。无论如何，修复都很简单：删除$True。

$Users = Get-AzureADUser -All -Filter "Usertype eq 'Member'"

在幕后，Get-AzureADUser 别名将命令重定向到 Get-EntraUser cmdlet，它支持相同的参数：

$Users = Get-AzureADUser -All -Filter "Usertype eq 'Member'"

鉴于其预期目的，Entra 模块中包含的 cmdlet 与 AzureAD 和 AzureADPrevIew 模块中的 cmdlet 相匹配也就不足为奇了。要查看可用命令的列表，请运行 Get-Command cmdlet。该列表还显示了可用的别名。

Get-Command -Module Microsoft.Graph.Entra

现在让我们找到用户帐户的管理员。通常，此命令可以正常工作：

$Manager = Get-AzureADUserManager -ObjectId $User.ObjectId

但如果用户帐户没有指定的管理员，则代码会出现以下错误：

Invoke-MgGraphRequest: GET https://graph.microsoft.com/v1.0/users/7bfd3f83-be63-4a5a-bbf8-c821e2836920/manager?$select=* HTTP/2.0 404 Not Found Cache-Control: no-cache Vary: Accept-Encoding
Strict-Transport-Security: max-age=31536000 request-id: 6622507b-c060-42f2-938e-a0225e756a70 client-request-id: 95d52d30-1faa-4891-82b2-783bfdf1e6bc x-ms-ags-diagnostic:
{"ServerInfo":{"DataCenter":"North Europe","Slice":"E","Ring":"4","ScaleUnit":"000","RoleInstance":"DU6PEPF00010AAA"}} x-ms-resource-unit: 1 Date: Fri, 28 Jun 2024 12:53:43 GMT
Content-Type: application/json Content-Encoding: gzip  {"error":{"code":"Request_ResourceNotFound","message":"Resource 'manager' does not exist or one of its queried reference-property objects are not
present.","innerError":{"date":"2024-06-28T12:53:43","request-id":"6622507b-c060-42f2-938e-a0225e756a70","client-request-id":"95d52d30-1faa-4891-82b2-783bfdf1e6bc"}}}

别名将 Get-AzureADUserManager cmdlet 转换为针对 Users API 的 Graph API 请求，该请求失败，因为请求中的选择查询未返回任何内容。

我可以继续强调这一点：将除了最简单的 AzureAD cmdlet 之外的所有用法转换为图形 API 请求是很困难的。您可以预料到会出现问题，并需要进行干预来解决问题。然后我问自己，如果预计会出现问题，为什么不简单地采用完整的 Microsoft Graph PowerShell SDK 并更新脚本来使用它呢？随着代码的更新，可以对其进行检查和改进，甚至可以通过利用图检索数据的方式来提高性能。

将脚本从 AzureAD 模块迁移到 Microsoft Graph PowerShell SDK 并不是非常困难，特别是如果您投资了 GitHub Copilot 并将其与 Visual Studio Code 结合使用。

使用与 Microsoft Graph PowerShell SDK 相同的权限

由于 Connect-Entra cmdlet 是 Connect-MgGraph 的别名，因此当您通过运行 Connect-Entra cmdlet 登录交互式会话时，会话继承 Microsoft Graph 命令行工具企业应用程序（或更确切地说是该应用程序的服务主体）持有的权限集。这些权限会随着时间的推移而累积，因此密切关注交互式会话期间可用的权限非常重要。 Microsoft 发布了 Entra 模块的最佳实践文章，建议使用注册应用程序而不是企业应用程序，以避免权限过载。我认为这是个好建议。

通过运行 Connect-Entra 以及通常不使用的 POP.AccessAsUser.All 权限范围，可以轻松确认这两个 cmdlet 使用相同的应用程序。 Microsoft Graph PowerShell SDK。向上弹出同意对话框，显示 Microsoft Graph 命令行工具应用程序正在寻求同意（图 1）。

精明的观察者会注意到 Microsoft Graph 命令行工具应用程序现已经过验证。这是消息中心帖子 MC804763（2024 年 6 月 24 日）中宣布的最新更改。以前，同意请求显示未经验证的应用程序，谁愿意同意可能来自未经验证的来源的应用程序的权限？微软为什么花了这么长时间才让该应用程序通过他们自己的应用程序合规性计划，这仍然是一个谜。

权衡 Entra PowerShell 模块

使用 Microsoft Graph PowerShell SDK 迁移脚本的缺点是，该 SDK 有自己的一组缺陷，可能会吸引粗心的开发人员。管道是一个很好的例子，因为 Graph SDK cmdlet 不支持这个基本的 PowerShell 概念。但 Entra PowerShell cmdlet 可以，这意味着类似这样的事情是可能的：

Get-AzureADUserManager -ObjectId cad05ccf-a359-4ac7-89e0-1e33bf37579e | Get-AzureADUser

微软还指出，新模块带有“人类可读的参数”，这是一种有趣的说法，Graph API 请求和 SDK cmdlet 有时享有只有经过深入研究才能理解的语法。

当它普遍可用时，Entra PowerShell 模块将发挥高度特定的作用，帮助尚未使用 cmdlet 将 PowerShell 脚本从旧的 AzureAD 和 AzureADPreview 模块迁移到现代基础的组织。微软表示，该模块是他们对 Microsoft Graph PowerShell SDK“持续承诺和增加投资”的一部分。如果是这样，我想知道为什么他们要花那么多精力来创建一个新模块，而不是修复 SDK 中的问题？拥有一个坚实可靠的模块似乎是比将开发工作分散到两个模块更好的策略。

我不会使用 Entra PowerShell 模块，因为我已经投入了四年的大部分时间来熟悉 Graph API。微软推出了一款可以帮助部分客户的工具，值得称赞，但我有一种挥之不去的感觉，即 Entra PowerShell 模块将成为混乱的根源。我的建议仍然是客户应该拥抱 Graph 并使用 Microsoft Graph PowerShell SDK。但请阅读 Entra 模块文档并做出自己的决定！