Командлеты Microsoft Entra версии 2 для управления группами

Статья
12/19/2024

В этой статье содержатся примеры использования PowerShell для управления группами в идентификаторе Microsoft Entra, части Microsoft Entra. Он также рассказывает, как настроиться с помощью модуля 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…

Теперь можно начать использование командлетов в модуле. Полное описание командлетов в модуле Microsoft Graph см. в справочной документации по Microsoft Graph PowerShell.

Подключение к каталогу

Прежде чем начать управление группами с помощью командлетов Microsoft Graph PowerShell, необходимо подключить сеанс PowerShell к каталогу, которому требуется управлять. Используйте следующую команду:

    PS C:\Windows\system32> Connect-MgGraph -Scopes "Group.ReadWrite.All"

Командлет запросит ввести учетные данные, которые вы хотите использовать для доступа к каталогу. В этом примере мы используем karen@drumkit.onmicrosoft.com для доступа к демонстрационнму каталогу. Командлет возвращает подтверждение, показывающее, что сеанс был успешно подключен к каталогу:

    Welcome To Microsoft Graph!

Теперь можно начать использовать командлеты MgGraph для управления группами в каталоге.

Получение сведений о группах

Чтобы получить существующие группы из каталога, используйте командлет Get-MgGroups.

Чтобы получить сведения о всех группах в каталоге, используйте командлет без параметров:

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

Командлет возвращает сведения о всех группах в подключенном каталоге.

Параметр -GroupId можно использовать для получения определенной группы, для которой указывается идентификатор объекта группы:

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

Командлет возвращает сведения о группе, идентификатор 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.onmicrosoft.com
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 реализуют стандарт запроса OData. Дополнительные сведения см. в разделе $filter статьи OData system query options using the OData endpoint (Параметры системных запросов OData с использованием конечной точки OData).

Ниже приведен пример, в который показано, как извлечь все группы, которые не применяют политику истечения срока действия.

Connect-MgGraph -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 -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. Этот командлет создает новую группу безопасности с именем Marketing:

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

New-MgGroup @param

Обновление групп

Чтобы обновить существующую группу, используйте командлет Update-MgGroup. В этом примере мы изменяем свойство DisplayName группы "Администраторы Intune". Сначала мы находим группу с помощью командлета Get-MgGroup и фильтруем с помощью атрибута 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 следующим образом:

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

Управление членством в группах

Добавить участников

Чтобы добавить новых участников в группу, используйте командлет New-MgGroupMember. Эта команда добавляет члена в группу Intune Administrators, которую мы использовали в предыдущем примере:

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

Параметр -GroupId является идентификатором объекта группы. Нам нужно указать идентификатор объекта группы, которую мы используем. -DirectoryObjectId — это ObjectID пользователя, который мы хотим добавить в качестве члена группы.

Получение сведений о членах

Чтобы получить существующие члены группы, используйте командлет Get-MgGroupMember, как в следующем примере:

    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, как показано ниже:

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

Проверка членства

Чтобы проверить членство в группах пользователя, используйте командлет Select-MgGroupIdsUserIsMemberOf. В качестве параметров этот командлет принимает идентификатор объекта пользователя, для которого выполняется проверка членства в группах, и список групп, в которых проверяется членство. Список групп необходимо указать в форме сложной переменной типа 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 -Scopes "Directory.ReadWrite.All"
 New-MgBetaDirectorySetting -BodyParameter $params

Управление владельцами групп

Чтобы добавить владельцев в группу, используйте командлет New-MgGroupOwner:

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

Параметр -GroupId — objectID группы, в которую мы хотим добавить владельца. -DirectoryObjectId — это ObjectID пользователя или субъекта-службы, который мы хотим добавить в качестве владельца.

Чтобы получить владельцев группы, используйте командлет Get-MgGroupOwner:

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

Командлет возвращает список владельцев (пользователей и субъектов-служб) для указанной группы:

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

Если вы хотите удалить владельца из группы, используйте командлет Remove-MgGroupOwnerByRef:

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

Зарезервированные псевдонимы

При создании группы пользователи указывают mailNickname или псевдоним, который система использует в качестве адреса электронной почты группы. Создание групп с любым из псевдонимов электронной почты с высоким уровнем привилегий ограничено глобальными администраторами Microsoft Entra.

abuse
администрирование
administrator
hostmaster
majordomo
postmaster
root
secure
security
ssl-admin
webmaster

Обратная запись групп в локальную среду

Сейчас многие группы по-прежнему управляются в Active Directory локально. Чтобы ответить на запросы синхронизации облачных групп обратно с локальной средой, функция обратной записи групп для идентификатора Microsoft Entra с помощью облачной синхронизации Microsoft Entra теперь доступна.

Внимание

Общедоступная предварительная версия групповой обратной записи версии 2 в Microsoft Entra Connect Sync больше не будет доступна после 30 июня 2024 г. С этого дня поддержка этой функции будет прекращена, и Connect Sync больше не будет поддерживать предоставление облачных групп безопасности в Active Directory. Функция будет продолжать работать и после даты прекращения поддержки; однако после этой даты она больше не будет поддерживаться и может прекратить работу в любое время без предварительного уведомления.

В Microsoft Entra Cloud Sync мы предлагаем аналогичную функцию под названием Подготовка группы в Active Directory, которую можно использовать вместо обратной записи группы версии 2 для подготовки облачных групп безопасности в Active Directory. Мы работаем над улучшением этой функции в Cloud Sync вместе с другими новыми функциями, которые мы разрабатываем в Cloud Sync.

Клиенты, использующие эту предварительную версию функции в Connect Sync, должны переключить конфигурацию с Connect Sync на Cloud Sync. Вы можете переместить всю гибридную синхронизацию в Cloud Sync (если она поддерживает ваши потребности). Вы также можете запустить Cloud Sync параллельно и перенести в Cloud Sync только подготовку облачной группы безопасности из Active Directory.

Для клиентов, которые подготавливают группы Microsoft 365 в Active Directory, можно продолжать использовать функцию обратной записи группы версии 1 для этой возможности.

Вы можете оценить переход исключительно на Cloud Sync, используя мастер синхронизации пользователей.

Следующие шаги

Дополнительную документацию по Microsoft Entra ID PowerShell можно найти в разделе Командлеты Microsoft Entra.

Поделиться через