用于组管理的 Microsoft Entra 版本 2 cmdlet

项目
08/28/2024

本文包含有关如何使用 PowerShell 在属于 Microsoft Entra 的 Microsoft Entra ID 中管理组的示例。此外，本文还介绍如何安装 Microsoft Graph PowerShell 模块。首先，必须下载 Microsoft Graph PowerShell 模块。

安装 Microsoft Graph PowerShell 模块

若要安装 MgGroup PowerShell 模块，请使用以下命令：

    PS C:\Windows\system32> Install-module Microsoft.Graph

若要验证模块是否可供使用，请运行下面的命令：

PS C:\Windows\system32> Get-Module -Name "*graph*"

ModuleType Version    PreRelease Name                                ExportedCommands
---------- -------    ---------- ----                                ----------------
Script     1.27.0                Microsoft.Graph.Authentication      {Add-MgEnvironment, Connect-MgGraph, Disconnect-MgGraph, Get-MgContext…}
Script     1.27.0                Microsoft.Graph.Groups              {Add-MgGroupDriveListContentTypeCopy, Add-MgGroupDriveListContentTypeCopyF…

现在可以开始使用模块中的 cmdlet 了。有关 Microsoft Graph 模块中的 cmdlet 的完整说明，请查看关于 Microsoft Graph PowerShell 的在线参考文档。

连接到目录

必须将 PowerShell 会话连接到要管理的目录，然后才能开始使用 Microsoft Graph PowerShell cmdlet 管理组。请使用以下命令：

    PS C:\Windows\system32> Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Group.ReadWrite.All"

该 cmdlet 会提示用户输入访问目录时需要使用的凭据。在此示例中，我们将使用 karen@drumkit.partner.onmschina.cn 访问演示目录。该 cmdlet 会返回一个确认，表明会话已成功连接到目录：

    Welcome To Microsoft Graph!

现在可以开始使用 MgGraph cmdlet 管理目录中的组。

检索组

若要从目录中检索现有组，请使用 Get-MgGroups cmdlet。

若要检索目录中的所有组，请使用不带参数的 cmdlet：

    PS C:\Windows\system32> Get-MgGroup -All

该 cmdlet 会返回已连接目录中的所有组。

可以使用 -GroupId 参数检索已指定组 objectID 的特定组：

    PS C:\Windows\system32> Get-MgGroup -GroupId 5e3eba05-6c2b-4555-9909-c08e997aab18 | fl

该 cmdlet 现在会返回其 objectID 与用户输入的参数值匹配的组：

AcceptedSenders               :
AllowExternalSenders          :
AppRoleAssignments            :
AssignedLabels                :
AssignedLicenses              :
AutoSubscribeNewMembers       :
Calendar                      : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCalendar
CalendarView                  :
Classification                :
Conversations                 :
CreatedDateTime               : 14-07-2023 14:25:49
CreatedOnBehalfOf             : Microsoft.Graph.PowerShell.Models.MicrosoftGraphDirectoryObject
DeletedDateTime               :
Description                   : Sales and Marketing
DisplayName                   : Sales and Marketing
Id                            : f76cbbb8-0581-4e01-a0d4-133d3ce9197f
IsArchived                    :
IsAssignableToRole            :
IsSubscribedByMail            :
LicenseProcessingState        : Microsoft.Graph.PowerShell.Models.MicrosoftGraphLicenseProcessingState
Mail                          : SalesAndMarketing@M365x64647001.partner.onmschina.cn
MailEnabled                   : True
MailNickname                  : SalesAndMarketing
RejectedSenders               :
RenewedDateTime               : 14-07-2023 14:25:49
SecurityEnabled               : True

可以使用 -filter 参数搜索特定组。此参数采用 ODATA 筛选器子句，并返回与筛选器匹配的所有组，如以下示例所示：

    PS C:\Windows\system32> Get-MgGroup -Filter "DisplayName eq 'Intune Administrators'"


    DeletionTimeStamp            :
    ObjectId                     : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
    ObjectType                   : Group
    Description                  : Intune Administrators
    DirSyncEnabled               :
    DisplayName                  : Intune Administrators
    LastDirSyncTime              :
    Mail                         :
    MailEnabled                  : False
    MailNickName                 : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
    OnPremisesSecurityIdentifier :
    ProvisioningErrors           : {}
    ProxyAddresses               : {}
    SecurityEnabled              : True

注意

MgGroup PowerShell cmdlet 会实现 OData 查询标准。有关详细信息，请参阅使用 OData 终结点的 OData 系统查询选项中的 $filter。

这里有一个示例，演示如何拉取未应用过期策略的所有组

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes 'Group.Read.All'
Get-MgGroup -ConsistencyLevel eventual -Count groupCount -Filter "NOT (expirationDateTime+ge+1900-01-01T00:00:00Z)" | Format-List Id

此示例与上一个示例相同，但脚本还将结果导出到 CSV。

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes 'Group.Read.All'
Get-MgGroup -ConsistencyLevel eventual -Count groupCount -Filter "NOT (expirationDateTime+ge+1900-01-01T00:00:00Z)" | Format-List Id |Export-Csv -Path {path} -NoTypeInformation

最后一个示例演示如何仅检索属于 Teams 的组

Get-MgGroup -ConsistencyLevel eventual -Count groupCount -Filter "NOT (expirationDateTime+ge+1900-01-01T00:00:00Z) and resourceProvisioningOptions/any(p:p eq 'Team')" | Format-List Id, expirationDateTime, resourceProvisioningOptions

创建组

若要在目录中创建新组，可使用 New-MgGroup cmdlet。此 cmdlet 创建名为“Marketing”的新安全组：

$param = @{
 description="My Demo Group"
 displayName="DemoGroup"
 mailEnabled=$false
 securityEnabled=$true
 mailNickname="Demo"
}

New-MgGroup @param

更新组

若要更新现有组，请使用 Update-MgGroup cmdlet。在此示例中，我们将更改“Intune 管理员”组的 DisplayName 属性。首先，我们将使用 Get-MgGroup cmdlet 查找该组，然后使用 DisplayName 属性进行筛选：

    PS C:\Windows\system32> Get-MgGroup -Filter "DisplayName eq 'Intune Administrators'"


    DeletionTimeStamp            :
    ObjectId                     : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
    ObjectType                   : Group
    Description                  : Intune Administrators
    DirSyncEnabled               :
    DisplayName                  : Intune Administrators
    LastDirSyncTime              :
    Mail                         :
    MailEnabled                  : False
    MailNickName                 : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
    OnPremisesSecurityIdentifier :
    ProvisioningErrors           : {}
    ProxyAddresses               : {}
    SecurityEnabled              : True

接下来，我们会将 Description 属性更改为新值“Intune 设备管理员”：

    PS C:\Windows\system32> Update-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b -Description "Demo Group Updated"

现在，如果我们再次找到该组，我们会看到 Description 属性已更新以反映新值：

    PS C:\Windows\system32> Get-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b | select displayname, description

    DisplayName Description
    ----------- -----------
    DemoGroup   Demo Group Updated

删除组

若要从目录中删除组，请使用 Remove-MgGroup cmdlet，如下所示：

    PS C:\Windows\system32> Remove-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b

管理组成员身份

添加成员

若要向组添加新成员，请使用 New-MgGroupMember cmdlet。该命令将成员添加到我们在上一示例中使用的“Intune 管理员”组：

    PS C:\Windows\system32> New-MgGroupMember -GroupId f76cbbb8-0581-4e01-a0d4-133d3ce9197f -DirectoryObjectId a88762b7-ce17-40e9-b417-0add1848eb68

-GroupId 参数是要将成员添加到的组的 ObjectID，-DirectoryObjectId 是要作为成员添加到组的用户的 ObjectID。

获取成员

若要获取组的现有成员，请使用 Get-MgGroupMember cmdlet，如以下示例所示：

    PS C:\Windows\system32> Get-MgGroupMember -GroupId 2c52c779-8587-48c5-9d4a-c474f2a66cf4

Id                                   DeletedDateTime
--                                   ---------------
aaaaaaaa-bbbb-cccc-1111-222222222222
bbbbbbbb-cccc-dddd-2222-333333333333

移除成员

若要删除之前添加到组的成员，请使用 Remove-MgGroupMember cmdlet，如下所示：

    PS C:\Windows\system32> Remove-MgGroupMemberByRef -DirectoryObjectId 00aa00aa-bb11-cc22-dd33-44ee44ee44ee -GroupId 2c52c779-8587-48c5-9d4a-c474f2a66cf4

验证成员

若要验证用户的组成员身份，请使用 Select-MgGroupIdsUserIsMemberOf cmdlet。该 cmdlet 使用用户的 ObjectId 作为参数，以便检查组成员身份；同时使用组列表作为参数来检查成员身份。组列表必须以类型为“Microsoft.Open.AzureAD.Model.GroupIdsForMembershipCheck”的复合变量形式提供，因此必须先创建该类型的变量：

Get-MgUserMemberOf -UserId 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

Id                                   DisplayName Description GroupTypes AccessType
--                                   ----------- ----------- ---------- ----------
5dc16449-3420-4ad5-9634-49cd04eceba0 demogroup   demogroup    {Unified}

返回的值是该用户所在组的列表。也可通过 Select-MgGroupIdsContactIsMemberOf、Select-MgGroupIdsGroupIsMemberOf 或 Select-MgGroupIdsServicePrincipalIsMemberOf 应用此方法，来检查特定组列表的联系人、组或服务主体成员身份

禁止用户创建组

可以禁止非管理员用户创建安全组。 Microsoft Online Directory Services (MSODS) 的默认行为是允许非管理员用户创建组，无论是否还启用了自助服务组管理 (SSGM)。 SSGM 设置仅控制“我的组”门户中的行为。

若要对非管理员用户禁用组创建，请执行以下操作：

验证是否允许非管理员用户创建组：

PS C:\> Get-MgBetaDirectorySetting | select -ExpandProperty values

 Name                            Value
 ----                            -----
 NewUnifiedGroupWritebackDefault true
 EnableMIPLabels                 false
 CustomBlockedWordsList
 EnableMSStandardBlockedWords    false
 ClassificationDescriptions
 DefaultClassification
 PrefixSuffixNamingRequirement
 AllowGuestsToBeGroupOwner       false
 AllowGuestsToAccessGroups       true
 GuestUsageGuidelinesUrl
 GroupCreationAllowedGroupId
 AllowToAddGuests                true
 UsageGuidelinesUrl
 ClassificationList
 EnableGroupCreation             true

如果它返回 EnableGroupCreation : True，则非管理员用户可以创建组。若要禁用此功能，请执行以下操作：

 Install-Module Microsoft.Graph.Beta.Identity.DirectoryManagement
 Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement
 $params = @{
 TemplateId = "62375ab9-6b52-47ed-826b-58e47e0e304b"
 Values = @(		
 	@{
 		Name = "EnableGroupCreation"
 		Value = "false"
 	}		
 )
 }
 Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Directory.ReadWrite.All"
 New-MgBetaDirectorySetting -BodyParameter $params

管理组的所有者

若要向组添加所有者，请使用 New-MgGroupOwner cmdlet：

    PS C:\Windows\system32> New-MgGroupOwner -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497 -DirectoryObjectId 92a0dad0-7c9e-472f-b2a3-0fe2c9a02867

-GroupId 参数是要将所有者添加到的组的 ObjectID，-DirectoryObjectId 是要作为所有者添加的用户或服务主体的 ObjectID。

若要检索组的所有者，请使用 Get-MgGroupOwner cmdlet：

    PS C:\Windows\system32> Get-MgGroupOwner -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497

该 cmdlet 将返回指定组的所有者（用户和服务主体）的列表：

    Id                                       DeletedDateTime
    --                                       ---------------
    8ee754e0-743e-4231-ace4-c28d20cf2841
    85b1df54-e5c0-4cfd-a20b-8bc1a2ca7865
    4451b332-2294-4dcf-a214-6cc805016c50

若需从组中移除所有者，请使用 Remove-MgGroupOwnerByRef cmdlet：

    PS C:\Windows\system32> Remove-MgGroupOwnerByRef -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497 -DirectoryObjectId 92a0dad0-7c9e-472f-b2a3-0fe2c9a02867

保留的别名

创建组后，某些终结点允许最终用户指定一个 mailNickname 或别名，用作组的电子邮件地址的一部分。仅 Microsoft Entra 全局管理员可以创建具有以下权限较高的电子邮件别名的组。

abuse
admin
主要区域中的
hostmaster
majordomo
postmaster
root
secure
security
ssl-admin
webmaster

组写回到本地

重要

2024 年 6 月 30 日之后，Microsoft Entra Connect Sync 将不再提供组写回 V2 (GWB) 的公共预览版。此功能将于该日期停止使用，Connect Sync 不再支持将云安全组预配到 Active Directory。该功能将在停止使用日期之后继续运行；但是，在此日期之后将不再获得支持，并且可能随时停止运行，恕不另行通知。

对于将 Microsoft 365 组预配到 Active Directory 的客户，可以继续使用组写回 v1 实现此功能。

后续步骤

如需更多 Azure Active Directory PowerShell 文档，可参阅 Microsoft Entra Cmdlet。

通过