Cmdlets do Microsoft Entra versão 2 para gerenciamento de grupos
Este artigo contém exemplos de como usar o PowerShell para gerenciar grupos no Microsoft Entra ID, parte do Microsoft Entra. Ele também explica como configurar usando o módulo PowerShell do Microsoft Graph. Primeiramente, você deve baixar o módulo PowerShell do Microsoft Graph.
Instale o módulo PowerShell do Microsoft Graph
Para instalar o módulo do PowerShell do MgGroup, use os seguintes comandos:
PS C:\Windows\system32> Install-module Microsoft.Graph
Para verificar se o módulo está pronto para ser usado, 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 do módulo. Para obter uma descrição completa dos cmdlets no módulo do Microsoft Graph, consulte a documentação de referência online do PowerShell do Microsoft Graph.
Conectar ao diretório
Antes de começar a gerenciar grupos usando cmdlets do PowerShell do Microsoft Graph, você deve conectar a sessão do PowerShell ao diretório que deseja gerenciar. Use o seguinte comando:
PS C:\Windows\system32> Connect-MgGraph -Scopes "Group.ReadWrite.All"
O cmdlet solicita as credenciais que você deseja usar para acessar o 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 conexão da sessão com o diretório foi bem-sucedida:
Welcome To Microsoft Graph!
Agora você pode começar a usar os cmdlets do MgGraph para gerenciar grupos no diretório.
Recuperar grupos
Para recuperar grupos existentes do seu 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 especifica o objectID do grupo:
PS C:\Windows\system32> Get-MgGroup -GroupId 5e3eba05-6c2b-4555-9909-c08e997aab18 | fl
Agora, o cmdlet 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 procurar 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
Observação
Os cmdlets do PowerShell do MgGroup implementam o padrão de consulta OData. Para saber mais, confira $filter em Opções de consulta do sistema OData usando o ponto de extremidade do OData.
Criar grupos
Para criar um novo grupo no seu diretório, use o cmdlet New-MgGroup. Esse 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 "Intune Administrators". Primeiramente, vamos localizar o grupo usando o cmdlet Get-MgGroup e filtrar 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, vamos mudar a propriedade Description para o novo valor "Intune Device Administrators":
PS C:\Windows\system32> Update-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b -Description "Demo Group Updated"
Agora, se localizarmos o grupo novamente, veremos que a propriedade Description foi 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
Excluir 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
Gerenciar associação ao grupo
Adicionar membros
Para adicionar novos membros a um grupo, use o cmdlet Add-MgGroupMember. Esse comando adiciona um membro ao grupo Intune Administrators que usamos 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 -DirectoryObjectId é o ObjectID do usuário que queremos adicionar como um 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. Esse cmdlet utiliza como seus parâmetros o ObjectId do usuário do qual verifica as associações de grupo e uma lista de grupos da qual verifica as associações. A lista de grupos deve ser fornecida na forma de uma variável complexa do tipo "Microsoft.Open.AzureAD.Model.GroupIdsForMembershipCheck". Desse modo, devemos criar primeiro 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 grupo por seus usuários
É possível 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, quer o gerenciamento de grupo de autoatendimento (SSGM) também esteja ou não habilitado. A configuração do SSGM controla o comportamento apenas no painel de acesso Meus Aplicativos.
Para desabilitar a criação de grupos por 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 retornar
EnableGroupCreation : True, os usuários não administradores podem criar grupos. Para desabilitar 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 Add-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 -DirectoryObjectId é o ObjectID do usuário ou da 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) do 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
Aliases reservados
Quando um grupo é criado, certos pontos de extremidade permitem que o usuário final especifique um mailNickname ou o alias a ser usado como parte do endereço de email do grupo. Grupos com os aliases de email altamente privilegiados a seguir só podem ser criados por um administrador global do Microsoft Entra.
- abuso
- administrador
- administrator
- hostmaster
- majordomo
- postmaster
- root
- seguro
- segurança
- ssl-admin
- webmaster
Write-back de grupo para o local (versão prévia)
Atualmente, muitos grupos ainda são gerenciados no Active Directory local. O recurso de write-back de grupos do Microsoft 365 para o Microsoft Entra ID agora está disponível em versão prévia para responder às solicitações de sincronização de grupos na nuvem com o local.
Os grupos do Microsoft 365 são criados e gerenciados na nuvem. A funcionalidade de write-back permite fazer write-back dos grupos do Microsoft 365 como grupos de distribuição em uma floresta do Active Directory com o Exchange instalado. Os usuários com caixas de correio do Exchange local podem enviar e receber emails desses grupos. O recurso de write-back de grupos não dá suporte a grupos de segurança ou de distribuição do Microsoft Entra.
Para saber mais, confira a documentação do serviço de sincronização do Microsoft Entra Connect.
O write-back de grupos do Microsoft 365 é uma versão prévia pública do recurso do Microsoft Entra ID e está disponível com qualquer plano de licença pago do Microsoft Entra ID. Para obter mais informações, consulte Termos de Licença Universal para Serviços Online.
Próximas etapas
É possível encontrar mais documentações do PowerShell do Azure Active Directory em Cmdlets do Microsoft Entra.