Gerar Relatórios com Get-AdGroupMember no PowerShell

A popular use of PowerShell is working with Active Directory Directory Services (AD). There are so many time-saving things PowerShell can do with AD objects. Using the PowerShell Get-ADGroupMember cmdlet and other cmdlets can save you a ton of time.

Grupos do Active Directory são uma ótima maneira de segmentar contas de usuário. Grupos permitem que os administradores definam o acesso a recursos em muitos sistemas.

Relacionado:Gerenciando Grupos do Active Directory usando Get-AdGroup e PowerShell

Neste artigo, vamos usar o PowerShell para obter membros do grupo AD e exportar esses membros. Você pode usar essas informações para gerar diversos relatórios interessantes.

Gerencie e Relate o Active Directory, Exchange e Microsoft 365 com o ManageEngine ADManager Plus. Baixe a versão de avaliação gratuita!

Pré-requisitos

Se você quiser seguir este artigo, certifique-se de ter os seguintes requisitos prontos:

• Trabalhando em um computador com Windows 10, associado ao domínio
• Conectado com um usuário que pode ler grupos AD e contas de usuário
• Tenha o módulo PowerShell do Active Directory instalado

Aprendendo o Básico

Para consultar grupos e membros de grupos do AD, você tem dois cmdlets do PowerShell à sua disposição – Get-AdGroup e Get-AdGroupMember.

O comando Get-ADGroup consulta um controlador de domínio e retorna objetos de grupo AD. Get-AdGroupMember examina cada grupo e retorna todas as contas de usuário, grupos, contatos e outros objetos que existem nesse grupo.

Obtendo Grupos AD

Para encontrar grupos AD com PowerShell, você pode usar o cmdlet Get-ADGroup. Sem parâmetros, Get-ADGroup irá consultar o AD e retornar todos os grupos em um domínio usando o parâmetro Filter. O parâmetro Filter é necessário. Ele existe para limitar os grupos retornados com base em vários critérios.

Por exemplo, para encontrar todos os grupos sem considerar nenhum critério, use Get-ADGroup e especifique um caractere curinga (asterisco) para o parâmetro Filter. Você pode ver um exemplo abaixo. Percorrer todos esses grupos pode levar algum tempo se você tiver centenas ou até milhares em seu domínio.

Get-ADGroup -Filter *

Se você precisa encontrar um único grupo, pode usar o parâmetro Identity.

O parâmetro Identity é um parâmetro comum entre todos os cmdlets do PowerShell do Active Directory. Ele permite limitar sua consulta a um único objeto AD. Por exemplo, se você precisar verificar se um grupo chamado HR existe, você pode descobrir executando o comando abaixo.

Get-ADGroup -Identity 'HR'

Obtendo Membros do Grupo AD com Get-AdGroupMember

Usar o PowerShell para listar membros de um grupo do AD requer o cmdlet Get-ADGroupMember. Este cmdlet obtém usuários, grupos e objetos de computador em um grupo específico. Talvez você precise encontrar todos os membros do grupo Administradores. Em sua forma mais simples, você simplesmente usaria o parâmetro Identity novamente especificando o nome do grupo como abaixo.

Get-ADGroupMember -Identity 'Administrators'

Observe que Get-AdGroupMember apenas retorna a associação do grupo para usuários, grupos e computadores. Não retornará outros objetos AD como contatos.

Enumerar Membros do Grupo Dentro de Outros Membros de Grupo

Como você pode saber, os grupos do AD não só podem conter contas de usuário, mas também outros grupos, também chamados de aninhamento. Quando um grupo está aninhado dentro de outro grupo, os membros desse grupo herdam as mesmas permissões atribuídas ao grupo pai.

Por padrão, o cmdlet Get-AdGroupMember do PowerShell não retorna membros de grupos aninhados. Para remediar isso, você pode usar o parâmetro Recursive. Por exemplo, você poderia encontrar membros de grupos aninhados dentro do grupo HR usando o parâmetro Recursive conforme mostrado abaixo.

Get-ADGroupMember -Identity 'HR' -Recursive

Relacionado:Como Auditar Associações de Membros de Grupos do Active Directory com PowerShell

Obtendo Múltiplos Grupos/Membros de uma Só Vez

Se precisar consultar o AD para muitos grupos ou membros do grupo de uma só vez, também pode fazer isso usando um loop foreach do PowerShell. Um loop foreach executa um comando ou código para cada item em uma coleção. Neste caso, essa coleção será uma lista de nomes de grupos.

Talvez precise encontrar todos os membros do grupo nos grupos HR, Accounting, e IT. Para fazer isso, primeiro criaria uma coleção ou array com esses nomes de grupo. O exemplo abaixo define essa coleção como $groupNames. Em seguida, para cada nome nessa coleção, execute Get-ADGroupMember fornecendo o nome de cada grupo ao parâmetro Identity.

$groupNames = 'HR','Accounting','IT'
foreach ($group in $groupNames) {
    Get-ADGroupMember -Identity $group
}

Também pode usar o ForEach-Object cmdlet para percorrer grupos.

Usando Credenciais Alternativas

Assim como muitos outros cmdlets do PowerShell, os cmdlets de grupo AD têm um parâmetro Credential. Por padrão, sempre que executa um cmdlet de grupo AD, ele usa suas credenciais conectadas para consultar o Active Directory. Esse comportamento exige que esteja em um computador associado a um domínio conectado como um usuário do Active Directory com permissão.

Mas e se estiver num computador de grupo de trabalho ou precisar de autenticar-se no AD como um utilizador diferente? Nesse caso, pode utilizar o parâmetro Credential. Este parâmetro permite-lhe especificar um nome de utilizador e palavra-passe para utilizar na autenticação.

Por exemplo, talvez a sua conta de utilizador não tenha permissões para realizar uma tarefa no AD. Tem uma conta de serviço com direitos adicionais. Pode estar conectado como um utilizador padrão e ainda assim autenticar-se com a conta de serviço, como mostrado abaixo.

O cmdlet Get-Credential solicita um nome de utilizador/palavra-passe para criar uma credencial. Esta credencial é então passada para o cmdlet Get-AdGroup para autenticação.

Get-ADGroup -Identity 'HR' -Credential (Get-Credential)

O parâmetro Credential é ubíquo no PowerShell para fornecer credenciais de autenticação. Para obter mais informações, leia Usando o cmdlet Get-Credential do PowerShell e todas as coisas sobre credenciais.

Obter Membros de Grupo com Get-ADGroup?

Pode parecer contra-intuitivo, mas também pode obter membros de grupo com o cmdlet Get-ADGroup.

Acontece que o Get-ADGroup retorna uma propriedade para cada grupo chamada membros. Esta é uma coleção de objetos AD que são membros de um grupo.

Por exemplo, para encontrar membros de grupo nesse HR grupo novamente sem usar Get-ADGroupMember, poderia fazer algo assim:

Get-ADGroup -Identity 'HR' -Properties members

Por que usar este método em vez do outro? A principal diferença é que as propriedades members contêm todos os tipos de objetos AD – não apenas usuários, computadores e outros grupos.

Talvez você tenha contatos dentro de vários grupos. Quando você executa Get-ADGroupMember, esses contatos não apareceriam. Mas se você disser para Get-ADGroup retornar todos os membros desse grupo e expandir essa coleção como mostrado abaixo, você verá os contatos.

Get-ADGroup -Identity 'HR' -Properties members | Select-Object -ExpandProperty members

Encontrando Atributos AD Específicos

Na seção básica acima, você simplesmente estava retornando todos os grupos e membros do grupo. As informações retornadas para cada grupo e membro do grupo são apenas um subconjunto dos atributos AD associados a cada tipo de objeto.

Talvez você queira ver o endereço de e-mail de uma conta de usuário, data do último logon ou outro atributo AD associado? Para fazer isso, você precisará ser criativo.

Talvez você tenha conseguido encontrar todos os membros do grupo HR mas precise também ver o endereço de e-mail de cada conta de usuário?

$groupMembers = (Get-ADGroup -Identity 'HR' -Properties members).members
$groupMembers | Select-Object -Property Name, @{Name='Member';exp={Get-AdUser -Identity $_.Name -Properties emailAddress,lastlogonDate}}

Filtrando Resultados

Até este ponto, você encontrou todos os grupos e membros do grupo, mas em um ambiente de trabalho do dia a dia, raramente você precisará fazer isso. É provável que você precise apenas encontrar um número limitado de cada item. Os cmdlets do grupo AD têm algumas maneiras de lidar com isso.

O Parâmetro Filter

Como mencionado anteriormente, ambos os cmdlets têm o parâmetro Filter. Este parâmetro permite limitar o que é retornado de muitas maneiras diferentes fora do escopo deste artigo.

Utilizando o parâmetro Filter, você pode limitar os resultados por qualquer atributo AD, como nome, tipo de grupo, endereço de e-mail, último logon para usuários, entre outros.

Por exemplo, talvez você queira encontrar apenas grupos de segurança. Nesse caso, você especificaria um atributo GroupCategory e definiria uma condição para garantir que apenas grupos Security sejam retornados.

Get-ADGroup -Filter 'GroupCategory -eq "Security"'

Talvez você queira encontrar todos os grupos de segurança, mas eles não devem ser grupos locais do domínio. Nesse caso, você adicionaria outra condição (desta vez usando o operador -ne) para evitar que grupos locais do domínio sejam retornados.

Get-ADGroup -Filter 'GroupCategory -eq "Security" -and GroupScope -ne "DomainLocal"'

Se você deseja aprender como criar filtros de consulta, certifique-se de verificar Aprendendo Filtros de Active Directory e LDAP no PowerShell.

Limitando os Resultados de Grupo por Unidade Organizacional (OU)

Talvez você tenha vários grupos aninhados em OUs. Você não necessariamente deseja encontrar todos os grupos, mas apenas os grupos em uma OU específica. Nesse caso, você pode usar o parâmetro SearchBase.

O parâmetro SearchBase permite que você especifique o nome distintivo (DN) de uma OU para começar a procurar grupos. Por exemplo, talvez você tenha uma OU chamada Locations na raiz do seu domínio. Na OU Locations, você tem cada OU de localização criada, como Austin, NYC, e Los Angeles. Você está apenas procurando grupos na OU NYC e precisa restringir a visualização dos outros.

Uma estrutura de OU AD de exemplo é mostrada abaixo. Observe que outros grupos existem fora das OUs Locations.

company.local
- Locations
  - Austin
  - NYC
    - Group 1
    - Group 2
  - Los Angeles
- Computers
  - Group 3
  - Group 4
- Service Accounts

Talvez precise encontrar todos os grupos AD que estão apenas na OU NYC. Para limitar a consulta, você usaria o parâmetro SearchBase fornecendo o DN conforme mostrado abaixo. Todos os grupos dentro da OU Locations são retornados.

Get-ADGroup -Filter '*' -SearchBase 'OU=Locations,OU=NYC,DC=company,DC=pri'

Mas agora você precisa encontrar todos os grupos em todas as UOs sob a OU Locations. Get-ADGroup retorna apenas grupos na OU Locations em si – não nas UOs filhas.

Para retornar grupos dentro de UOs filhas, você precisaria usar o parâmetro SearchScope. Este parâmetro é semelhante ao parâmetro Recursive no sentido de que ele também inspecionará objetos filhos.

Por exemplo, para encontrar todos os grupos em qualquer OU sob a OU Locations, especifique Subtree ou 2. Este valor para SearchScope diz ao Get-ADGroup para olhar recursivamente para todos os filhos, netos e assim por diante das UOs.

Get-ADGroup -Filter '*' -SearchBase 'OU=Locations,DC=company,DC=pri' -SearchScope 2

Para uma explicação completa das opções do parâmetro SearchScope, consulte a documentação do Get-ADGroup.

Exportando Grupos e Membros AD

Agora você sabe como consultar e retornar os grupos e membros de grupo de que precisa. Todas essas informações são enviadas para o console do PowerShell. Mas agora você precisa colocar essas informações em um arquivo CSV ou planilha do Excel.

A única coisa que você precisa fazer agora é enviar todas essas informações para um arquivo.

Exportando para um CSV

Um formato popular para exportar informações do AD é um CSV. O PowerShell possui um cmdlet útil que permite criar facilmente arquivos CSV a partir da saída do PowerShell chamado Export-Csv.

Pode criar um arquivo CSV a partir de qualquer comando abordado neste artigo, redirecionando-o para Export-Csv. Usando o exemplo abaixo, todo o output que Get-AdGroup teria retornado para o console será redirecionado para um arquivo CSV.

Get-ADGroup -Filter '*' -SearchBase 'OU=Locations,DC=company,DC=pri' -SearchScope 2 | Export-Csv -Path 'departmental_groups.csv' -NoTypeInformation

Para obter mais informações sobre este útil cmdlet, consulte Export-Csv: A Forma PowerShell de Tratar Arquivos CSV como Cidadãos de Primeira Classe.

Também é possível exportar facilmente os resultados para CSV através do cmdlet Get-AdGroupMember.

Exportando para o Excel

O PowerShell não possui uma maneira nativa de exportar informações para o Excel. No entanto, você sempre pode baixar o módulo da comunidade chamado ImportExcel. Esse módulo traz capacidades de exportação semelhantes a CSV diretamente para planilhas do Excel. Para instalar o módulo PowerShell, execute Install-Module ImportExcel -Scope CurrentUser.

Usando o exemplo acima, em vez de um arquivo CSV, se precisar exportar os grupos para uma planilha do Excel, você usaria o cmdlet Export-Excel conforme mostrado abaixo.

Encontre senhas vazadas e inseguras em seu Active Directory verificando a lista de senhas do NCSC.

Get-ADGroup -Filter '*' -SearchBase 'OU=Locations,DC=company,DC=pri' -SearchScope 2 | Export-Excel -Path 'departmental_groups.csv'

O módulo ImportExcel possui uma ampla gama de funcionalidades para trabalhar com o Excel. Se você precisa de uma planilha mais sofisticada, provavelmente possui uma função para você.

Para obter mais informações sobre o uso do módulo ImportExcel, leia este artigo. Ele oferece uma ótima introdução a alguns casos de uso comuns que ele pode lidar.

Gerencie e Relate o Active Directory, Exchange e o Microsoft 365 com o ManageEngine ADManager Plus. Faça o Download da Versão de Avaliação Gratuita!

Conclusão

Com apenas dois cmdlets do PowerShell, você pode fazer praticamente qualquer coisa com grupos AD. Este artigo foi apenas uma introdução às funcionalidades disponíveis para você. Use o conhecimento reunido aqui, siga alguns dos links para mergulhos mais profundos nos tópicos do artigo e veja o que você pode construir!