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 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

Aqui você tem um exemplo que mostra como puxar 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 filtrando 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 associaçã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 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
--                                   ---------------
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 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 SSGM controla o comportamento somente no portal Meus Grupos.

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

1. 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             true
   

2. Se 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 o local

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 para ID do Microsoft Entra usando a sincronização de nuvem do Microsoft Entra agora está disponível.

Próximos passos

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

• Gerenciando o acesso a recursos com grupos do Microsoft Entra
• Integrando suas identidades locais com o Microsoft Entra ID