Cmdlets do Microsoft Entra versão 2 para gerenciamento de grupos

Artigo
03/12/2025

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 com o módulo PowerShell do Microsoft Graph. 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                     : 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

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 endpoint OData.

Aqui tem um exemplo que mostra como extrair todos os grupos que não têm uma política de expiração aplicada

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

Este exemplo faz o mesmo que o anterior, mas o script também exporta os resultados para 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

Este último exemplo mostra como recuperar apenas grupos que pertencem ao 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

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 o filtro usando o atributo 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

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 filiação ao grupo

Adicionar membros

Para adicionar novos membros a um grupo, use o cmdlet New-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 grupo ObjectID. Precisamos especificar o ObjectID do grupo que estamos usando. O -DirectoryObjectId é o ObjectID do usuário que queremos adicionar como membro do 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
--                                   ---------------
aaaaaaaa-bbbb-cccc-1111-222222222222
bbbbbbbb-cccc-dddd-2222-333333333333

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 00aa00aa-bb11-cc22-dd33-44ee44ee44ee -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 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

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 este método para verificar a membresia de Contactos, Grupos ou Principais de Serviço para uma dada 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 padrão criem grupos de segurança. O comportamento padrão no Microsoft Online Directory Services (MSODS) é permitir que usuários padrão criem grupos, independentemente de o gerenciamento de grupo de autoatendimento (SSGM) também estar habilitado ou não. A configuração SSGM controla o comportamento somente no portal Meus Grupos.

Para desativar a criação de grupos para usuários padrão:

Verifique se os usuários padrão 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             true

Se ele retornar EnableGroupCreation : True, os usuários padrão 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. 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 você cria um grupo, os usuários especificam um mailNickname ou alias que o sistema usa como parte do endereço de e-mail do grupo. A criação de grupos com qualquer um dos aliases de e-mail altamente privilegiados listados é limitada aos Administradores Globais do Microsoft Entra.

abuso
admin
administrador
administrador de domínio
Majordomo
Chefe dos Correios
raiz
segura
Segurança
ssl-admin
administrador do site

Reversão de grupo para servidores locais

Atualmente, muitos grupos ainda são gerenciados no Ative Directory local. Para atender a solicitações de sincronização de grupos de nuvem para o local, a funcionalidade de writeback de grupos do Microsoft Entra ID, usando a sincronização de nuvem do Microsoft Entra, já está disponível.

Importante

A visualização pública do Group Writeback v2 no Microsoft Entra Connect Sync não estará mais disponível após 30 de junho de 2024. Esta funcionalidade será descontinuada nesta data, e já não haverá suporte no Connect Sync para aprovisionar grupos de segurança na cloud para o Active Directory. A funcionalidade continuará a operar após a data de descontinuação. No entanto, deixará de receber suporte após esta data e poderá deixar de funcionar a qualquer momento sem aviso prévio.

Oferecemos funcionalidade semelhante na Microsoft Entra Cloud Sync denominada Aprovisionamento de Grupo para Active Directory, que pode utilizar em vez do Group Writeback v2 para aprovisionar grupos de segurança da cloud para Active Directory. Estamos a trabalhar para melhorar esta funcionalidade na Sincronização da Cloud, juntamente com outras novas funcionalidades que estamos a desenvolver na Sincronização da Cloud.

Os clientes que usam esta funcionalidade de pré-visualização na Sincronização de Ligação devem alternar a sua configuração da Sincronização de Ligação para a Sincronização na Cloud. Pode optar por mover toda a sincronização híbrida para a Sincronização na Cloud (se esta atender às suas necessidades). Também pode executar a Sincronização na Cloud em paralelo e mover apenas o aprovisionamento do grupo de segurança da cloud para o Active Directory através da Sincronização na Cloud.

Para clientes que aprovisionam grupos do Microsoft 365 para o Active Directory, pode continuar a utilizar a Escrita de Volta de Grupo v1 para esta funcionalidade.

Pode avaliar a mudança exclusivamente para o Cloud Sync utilizando o assistente de sincronização do utilizador.

Próximos passos

Você pode encontrar mais documentação do Microsoft Entra ID PowerShell em Microsoft Entra Cmdlets.

Partilhar via