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 : 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 "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 : 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, 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 New-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
-- ---------------
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
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 portal Meus Grupos.
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
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 pública do grupo Write-back v2 no Microsoft Entra Connect Sync não estará mais disponível após 30 de junho de 2024. Esse recurso será descontinuado nesta data e você não receberá mais suporte no Connect Sync para provisionar grupos de segurança de nuvem para o Active Directory. O recurso continuará operando além da data de descontinuação; no entanto, ele não receberá mais suporte após essa data e poderá deixar de funcionar a qualquer momento sem aviso prévio.
Oferecemos uma funcionalidade semelhante no Microsoft Entra Cloud Sync chamada Provisionamento de grupos para o Active Directory que pode ser usada em vez do grupo Writeback v2 para provisionar grupos de segurança de nuvem para o Active Directory. Estamos trabalhando para aprimorar essa funcionalidade no Cloud Sync, juntamente com outros novos recursos que estamos desenvolvendo no Cloud Sync.
Os clientes que usam esse recurso de visualização no Connect Sync devem alternar suas configurações do Connect Sync para o Cloud Sync. Você pode optar por mover toda a sua sincronização híbrida para o Cloud Sync (se ele atender às suas necessidades). Também pode executar o Cloud Sync lado a lado e mover apenas ao Cloud Sync o provisionamento de grupos de segurança da nuvem para o Active Directory.
Para clientes que provisionam grupos do Microsoft 365 para o Active Directory, é possível continuar usando o Group Writeback v1 para essa capacidade.
Você pode avaliar a mudança exclusivamente para o Cloud Sync usando o assistente de sincronização de usuários.
Próximas etapas
É possível encontrar mais documentações do PowerShell do Azure Active Directory em Cmdlets do Microsoft Entra.