Cmdlets do Microsoft Entra versão 2 para gerenciamento de grupos
Este artigo contém exemplos de como usar o PowerShell para gerenciar seus grupos no Microsoft Entra ID, parte do Microsoft Entra. Ele também informa como configurar o módulo Microsoft Graph PowerShell. Primeiro, você deve baixar o módulo do Microsoft Graph PowerShell.
Instalar o módulo do Microsoft Graph PowerShell
Para instalar o módulo MgGroup PowerShell, use os seguintes comandos:
PS C:\Windows\system32> Install-module Microsoft.Graph
Para verificar se o módulo está pronto para uso, use o seguinte comando:
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…
Agora você pode começar a usar os cmdlets no módulo. Para obter uma descrição completa dos cmdlets no módulo Microsoft Graph, consulte a documentação de referência online do Microsoft Graph PowerShell.
Conectar-se ao diretório
Antes de começar a gerenciar grupos usando cmdlets do Microsoft Graph PowerShell, você deve conectar sua sessão do PowerShell ao diretório que deseja gerenciar. Utilize o seguinte comando:
PS C:\Windows\system32> Connect-MgGraph -Scopes "Group.ReadWrite.All"
O cmdlet solicita as credenciais que você deseja usar para acessar seu diretório. Neste exemplo, estamos usando karen@drumkit.onmicrosoft.com para acessar o diretório de demonstração. O cmdlet retorna uma confirmação para mostrar que a sessão foi conectada com êxito ao seu diretório:
Welcome To Microsoft Graph!
Agora você pode começar a usar os cmdlets do MgGraph para gerenciar grupos em seu diretório.
Recuperar grupos
Para recuperar grupos existentes do diretório, use o cmdlet Get-MgGroups.
Para recuperar todos os grupos no diretório, use o cmdlet sem parâmetros:
PS C:\Windows\system32> Get-MgGroup -All
O cmdlet retorna todos os grupos no diretório conectado.
Você pode usar o parâmetro -GroupId para recuperar um grupo específico para o qual você especifica o objectID do grupo:
PS C:\Windows\system32> Get-MgGroup -GroupId 5e3eba05-6c2b-4555-9909-c08e997aab18 | fl
O cmdlet agora retorna o grupo cujo objectID corresponde ao valor do parâmetro inserido:
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
Você pode pesquisar um grupo específico usando o parâmetro -filter. Esse parâmetro usa uma cláusula de filtro ODATA e retorna todos os grupos que correspondem ao filtro, como no exemplo a seguir:
PS C:\Windows\system32> Get-MgGroup -Filter "DisplayName eq 'Intune Administrators'"
DeletionTimeStamp :
ObjectId : 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df
ObjectType : Group
Description : Intune Administrators
DirSyncEnabled :
DisplayName : Intune Administrators
LastDirSyncTime :
Mail :
MailEnabled : False
MailNickName : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
OnPremisesSecurityIdentifier :
ProvisioningErrors : {}
ProxyAddresses : {}
SecurityEnabled : True
Nota
Os cmdlets do PowerShell MgGroup implementam o padrão de consulta OData. Para obter mais informações, consulte $filter nas opções de consulta do sistema OData usando o ponto de extremidade OData.
Criar grupos
Para criar um novo grupo em seu diretório, use o cmdlet New-MgGroup. Este cmdlet cria um novo grupo de segurança chamado "Marketing":
$param = @{
description="My Demo Group"
displayName="DemoGroup"
mailEnabled=$false
securityEnabled=$true
mailNickname="Demo"
}
New-MgGroup @param
Atualizar grupos
Para atualizar um grupo existente, use o cmdlet Update-MgGroup. Neste exemplo, estamos alterando a propriedade DisplayName do grupo "Administradores do Intune". Primeiro, estamos localizando o grupo usando o cmdlet Get-MgGroup e filtrando usando o atributo DisplayName:
PS C:\Windows\system32> Get-MgGroup -Filter "DisplayName eq 'Intune Administrators'"
DeletionTimeStamp :
ObjectId : 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df
ObjectType : Group
Description : Intune Administrators
DirSyncEnabled :
DisplayName : Intune Administrators
LastDirSyncTime :
Mail :
MailEnabled : False
MailNickName : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
OnPremisesSecurityIdentifier :
ProvisioningErrors : {}
ProxyAddresses : {}
SecurityEnabled : True
Em seguida, estamos alterando a propriedade Description para o novo valor "Administradores de dispositivo do Intune":
PS C:\Windows\system32> Update-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b -Description "Demo Group Updated"
Agora, se encontrarmos o grupo novamente, veremos que a propriedade Description é atualizada para refletir o novo valor:
PS C:\Windows\system32> Get-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b | select displayname, description
DisplayName Description
----------- -----------
DemoGroup Demo Group Updated
Eliminar grupos
Para excluir grupos do diretório, use o cmdlet Remove-MgGroup da seguinte maneira:
PS C:\Windows\system32> Remove-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b
Gerir associação ao grupo
Adicionar membros
Para adicionar novos membros a um grupo, use o cmdlet Add-MgGroupMember. Este comando adiciona um membro ao grupo Administradores do Intune que utilizámos no exemplo anterior:
PS C:\Windows\system32> New-MgGroupMember -GroupId f76cbbb8-0581-4e01-a0d4-133d3ce9197f -DirectoryObjectId a88762b7-ce17-40e9-b417-0add1848eb68
O parâmetro -GroupId é o ObjectID do grupo ao qual queremos adicionar um membro, e o -DirectoryObjectId é o ObjectID do usuário que queremos adicionar como membro ao grupo.
Obter membros
Para obter os membros existentes de um grupo, use o cmdlet Get-MgGroupMember, como neste exemplo:
PS C:\Windows\system32> Get-MgGroupMember -GroupId 2c52c779-8587-48c5-9d4a-c474f2a66cf4
Id DeletedDateTime
-- ---------------
71b3857d-2a23-416d-bd22-a471854ddada
fd2d57c7-22ad-42cd-961a-7340fb2eb6b4
Remover membros
Para remover o membro que adicionamos anteriormente ao grupo, use o cmdlet Remove-MgGroupMember, conforme mostrado aqui:
PS C:\Windows\system32> Remove-MgGroupMemberByRef -DirectoryObjectId 053a6a7e-4a75-48bc-8324-d70f50ec0d91 -GroupId 2c52c779-8587-48c5-9d4a-c474f2a66cf4
Verificar membros
Para verificar as associações de grupo de um usuário, use o cmdlet Select-MgGroupIdsUserIsMemberOf. Este cmdlet toma como parâmetros o ObjectId do usuário para o qual verificar as associações de grupo e uma lista de grupos para os quais verificar as associações. A lista de grupos deve ser fornecida na forma de uma variável complexa do tipo "Microsoft.Open.AzureAD.Model.GroupIdsForMembershipCheck", portanto, primeiro devemos criar uma variável com esse tipo:
Get-MgUserMemberOf -UserId 053a6a7e-4a75-48bc-8324-d70f50ec0d91
Id DisplayName Description GroupTypes AccessType
-- ----------- ----------- ---------- ----------
5dc16449-3420-4ad5-9634-49cd04eceba0 demogroup demogroup {Unified}
O valor retornado é uma lista de grupos dos quais esse usuário é membro. Você também pode aplicar esse método para verificar a associação de Contatos, Grupos ou Entidades de Serviço para uma determinada lista de grupos, usando Select-MgGroupIdsContactIsMemberOf, Select-MgGroupIdsGroupIsMemberOf ou Select-MgGroupIdsServicePrincipalIsMemberOf
Desativar a criação de grupos pelos seus utilizadores
Você pode impedir que usuários não administradores criem grupos de segurança. O comportamento padrão no Microsoft Online Directory Services (MSODS) é permitir que usuários não administradores criem grupos, independentemente de o gerenciamento de grupo de autoatendimento (SSGM) também estar habilitado. A configuração do SSGM controla o comportamento somente no painel de acesso Meus Aplicativos.
Para desativar a criação de grupos para usuários não administradores:
Verifique se os usuários não administradores têm permissão para criar grupos:
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 trueSe ele retornar
EnableGroupCreation : True, os usuários não administradores poderão criar grupos. Para desativar esse recurso: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
Gerenciar proprietários de grupos
Para adicionar proprietários a um grupo, use o cmdlet New-MgGroupOwner:
PS C:\Windows\system32> New-MgGroupOwner -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497 -DirectoryObjectId 92a0dad0-7c9e-472f-b2a3-0fe2c9a02867
O parâmetro -GroupId é o ObjectID do grupo ao qual queremos adicionar um proprietário, e o -DirectoryObjectId é o ObjectID do usuário ou entidade de serviço que queremos adicionar como proprietário.
Para recuperar os proprietários de um grupo, use o cmdlet Get-MgGroupOwner:
PS C:\Windows\system32> Get-MgGroupOwner -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497
O cmdlet retorna a lista de proprietários (usuários e entidades de serviço) para o grupo especificado:
Id DeletedDateTime
-- ---------------
8ee754e0-743e-4231-ace4-c28d20cf2841
85b1df54-e5c0-4cfd-a20b-8bc1a2ca7865
4451b332-2294-4dcf-a214-6cc805016c50
Se quiser remover um proprietário de um grupo, use o cmdlet Remove-MgGroupOwnerByRef:
PS C:\Windows\system32> Remove-MgGroupOwnerByRef -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497 -DirectoryObjectId 92a0dad0-7c9e-472f-b2a3-0fe2c9a02867
Pseudónimos reservados
Quando um grupo é criado, determinados pontos de extremidade permitem que o usuário final especifique um mailNickname ou alias a ser usado como parte do endereço de e-mail do grupo. Os grupos com os seguintes aliases de e-mail altamente privilegiados só podem ser criados por um Administrador Global do Microsoft Entra.
- abuso
- administração
- administrador
- Hostmaster
- Majordomo
- Carteiro
- raiz
- segura
- Segurança
- ssl-admin
- webmaster
Write-back de grupo para local (visualização)
Atualmente, muitos grupos ainda são gerenciados no Ative Directory local. Para responder a solicitações de sincronização de grupos de nuvem de volta ao local, o recurso de write-back de grupos do Microsoft 365 para ID do Microsoft Entra agora está disponível para visualização.
Os grupos do Microsoft 365 são criados e gerenciados na nuvem. O recurso de write-back permite que você reescreva grupos do Microsoft 365 como grupos de distribuição em uma floresta do Ative Directory com o Exchange instalado. Os usuários com caixas de correio locais do Exchange podem enviar e receber emails desses grupos. O recurso de write-back de grupo não oferece suporte a grupos de segurança ou grupos de distribuição do Microsoft Entra.
Para obter mais detalhes, consulte a documentação do serviço Microsoft Entra Connect Sync.
O write-back de grupo do Microsoft 365 é um recurso de visualização pública do Microsoft Entra ID e está disponível com qualquer plano de licença pago do Microsoft Entra ID. Para obter mais informações sobre visualizações, consulte Termos de Licença Universal para Serviços Online.
Próximos passos
Você pode encontrar mais documentação do Azure Ative Directory PowerShell em Microsoft Entra Cmdlets.