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 : 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
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 ponto de extremidade OData.
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 : 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, 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 Add-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
-- ---------------
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. 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 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 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 do SSGM controla o comportamento somente no painel de acesso Meus Aplicativos.
Para desativar a criação de grupos para 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 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 provisionamento para o Ative Directory para grupos agora 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. Esse recurso será descontinuado nesta data e você não terá mais suporte no Connect Sync para provisionar grupos de segurança na nuvem para o Ative Directory.
Oferecemos funcionalidade semelhante no Microsoft Entra Cloud Sync chamada Provisionamento de Grupo para o Ative Directory que você pode usar em vez do Writeback de Grupo v2 para provisionar grupos de segurança de nuvem para o Ative Directory. Estamos a trabalhar para melhorar esta funcionalidade no Cloud Sync, juntamente com outras novas funcionalidades que estamos a desenvolver no Cloud Sync.
Os clientes que usam esse recurso de visualização no Connect Sync devem alternar sua configuração do Connect Sync para o Cloud Sync. Você pode optar por mover toda a sincronização híbrida para o Cloud Sync (se ele atender às suas necessidades). Você também pode executar o Cloud Sync lado a lado e mover apenas o provisionamento do grupo de segurança na nuvem para o Ative Directory para o Cloud Sync.
Para clientes que provisionam grupos do Microsoft 365 para o Ative Directory, você pode continuar usando o Write-back de Grupo v1 para esse recurso.
Você pode avaliar a mudança exclusivamente para o Cloud Sync usando o assistente de sincronização do usuário.
Próximos passos
Você pode encontrar mais documentação do Azure Ative Directory PowerShell em Microsoft Entra Cmdlets.