Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 : 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
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.
Aqui você tem um exemplo que mostra como efetuar pull de 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
Esse 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 os 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 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 "Administradores do Intune". Primeiro, estamos encontrando 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 Dispositivos do Intune":
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 New-MgGroupMember. Esse comando adiciona um membro ao grupo Administradores do Intune 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. Precisamos especificar a ObjectID do grupo que estamos usando. O -DirectoryObjectId é o ObjectID do usuário que desejamos 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. 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 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
Desabilitar a criação de grupo por seus usuários
Você pode impedir que usuários padrão criem grupos de segurança. O comportamento padrão no MSODS (Microsoft Online Directory Services) é permitir que usuários padrão criem grupos, independentemente de o SSGM (gerenciamento de grupo de autoatendimento) também estar habilitado ou não. A configuração do SSGM controla o comportamento apenas no portal Meus Grupos.
Para desabilitar a criação de grupo 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 trueSe retornar
EnableGroupCreation : True, os usuários padrão poderão 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 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 é a ObjectID do usuário ou entidade de serviço que desejamos 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 você cria um grupo, os usuários especificam um mailNickname ou alias que o sistema usa como parte do endereço de email do grupo. A criação de grupos com qualquer um dos aliases de email altamente privilegiados listados é limitada aos Administradores Globais do Microsoft Entra.
- abuso
- administrador
- administrador
- hostmaster
- majordomo
- postmaster
- raiz
- seguro
- segurança
- ssl-admin
- webmaster
Write-back de grupo para o local
Atualmente, muitos grupos ainda são gerenciados no Active Directory local. Para atender às solicitações de sincronização de grupos na nuvem de volta ao local, o recurso de write-back de grupos do Microsoft Entra ID usando a sincronização na nuvem do Microsoft Entra já está disponível.
Importante
A visualização do Write-back de grupo v2 no Microsoft Entra Connect Sync foi preterida e não tem mais suporte.
Você pode usar o Microsoft Entra Cloud Sync para provisionar grupos de segurança de nuvem no AD DS (Active Directory Domain Services) local.
Se você usar o Write-back de Grupo v2 no Microsoft Entra Connect Sync, deverá mover o cliente de sincronização para o Microsoft Entra Cloud Sync. Para verificar se você está qualificado para migrar para o Microsoft Entra Cloud Sync, use o assistente de sincronização do usuário.
Se você não puder usar o Microsoft Cloud Sync conforme recomendado pelo assistente, poderá executar o Microsoft Entra Cloud Sync lado a lado com o Microsoft Entra Connect Sync. Nesse caso, você pode executar o Microsoft Entra Cloud Sync apenas para provisionar grupos de segurança de nuvem no AD DS local.
Se você provisionar grupos do Microsoft 365 para o AD DS, poderá continuar usando o Write-back de Grupo v1.
Próximas etapas
Você pode encontrar mais documentação do PowerShell do Microsoft Entra ID em Microsoft Entra Cmdlets.