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

Обзор

В этой статье представлены примеры использования PowerShell для управления вашими группами в Microsoft Entra ID, частью Microsoft Entra. Он также рассказывает, как настроиться с помощью модуля Microsoft Graph PowerShell. Сначала необходимо скачать модуль Microsoft Graph PowerShell.

Необходимые условия

• Установлен Microsoft Graph PowerShell SDK.
• Войдите с учетной записью, которая имеет по крайней мере роль администратора групп .
• Область Group.ReadWrite.All разрешений должна быть одобрена для приложения Microsoft Graph PowerShell в вашем клиенте. При запуске Connect-MgGraphвам будет предложено предоставить согласие, если оно не было предоставлено ранее. Для первоначального согласия требуется учетная запись администратора. Дополнительные сведения см. разделе Начало работы с пакетом SDK 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-MgGroup cmdlet.

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

    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

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

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

$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, используемую в предыдущем примере:

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

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

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

Чтобы получить существующих членов группы, используйте 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-MgGroupMemberByRef командлет, как показано ниже:

    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-MgGroupIdsGroupIsMemberOfSelect-MgGroupIdsServicePrincipalIsMemberOf.

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

Вы можете запретить стандартным пользователям создавать группы безопасности. Поведение по умолчанию в службах microsoft Online Directory Services (MSODS) позволяет стандартным пользователям создавать группы, независимо от того, включена ли служба самостоятельного управления группами (SSGM). Параметры SSGM управляют поведением только на портале "Мои группы".

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

1. Убедитесь, что стандартные пользователи могут создавать группы:

   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
   

2. Если он возвращает 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 - идентификатор объекта пользователя или сервисного субъекта, которого нужно добавить в владельцы.

Чтобы получить владельцев группы, используйте командлет 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.

• злоупотребление
• админ
• администратор
• администратор хостинга
• управляющий домом
• начальник почтового отделения
• корень
• безопасный
• безопасность
• администратор SSL
• вебмастер

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

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

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

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

• Управление доступом к ресурсам с помощью групп Microsoft Entra
• Интеграция локальных идентификаторов с Microsoft Entra ID