Get-ADGroup : syntaxe, exemples et filtres PowerShell essentiels 🔍
Get-ADGroup est une cmdlet PowerShell Active Directory qui récupère un ou plusieurs objets groupe depuis l’annuaire. Elle permet de rechercher un groupe précis avec -Identity, de lister l’ensemble des groupes avec -Filter *, ou de cibler une unité d’organisation avec -SearchBase. Voici la syntaxe, les paramètres essentiels, des exemples directement exploitables, ainsi que les différences avec Get-ADGroupMember et Get-ADPrincipalGroupMembership.
Rôle de Get-ADGroup et prérequis
Get-ADGroup fait partie du module ActiveDirectory pour PowerShell, installé avec les outils d’administration de serveur distant (RSAT) ou disponible nativement sur un contrôleur de domaine. Cette cmdlet retourne des objets groupe Active Directory, avec leurs propriétés de base comme le nom, le SID ou le distinguished name, sans afficher leurs membres. Avant toute utilisation, le module doit être chargé :
Import-Module ActiveDirectory
Sur un poste équipé du module, l’import est généralement automatique dès la première commande utilisée. En cas d’erreur indiquant que le terme n’est pas reconnu, cet import manuel résout la majorité des cas.
Sur un poste de travail qui n’est pas un contrôleur de domaine, le module ActiveDirectory doit d’abord être installé via les fonctionnalités RSAT (Remote Server Administration Tools), disponibles sous Windows Server via le gestionnaire de serveur, ou sous Windows 10/11 via les fonctionnalités à la demande. Une fois installé, le module reste disponible sur le poste sans nécessiter de nouvelle installation à chaque session, seul l’import via Import-Module ActiveDirectory étant parfois requis selon la configuration du profil PowerShell.
Syntaxe minimale de Get-ADGroup
La forme la plus simple pour rechercher un groupe Active Directory précis repose sur le paramètre -Identity :
Get-ADGroup -Identity "GRP-Comptabilite"
Ce paramètre accepte le nom du groupe, son SID, son GUID ou son distinguished name complet. Il constitue la méthode la plus directe lorsque l’identifiant exact du groupe est déjà connu.
Lister tous les groupes Active Directory
Pour afficher l’ensemble des groupes présents dans l’annuaire, le paramètre -Filter avec un caractère générique suffit :
Get-ADGroup -Filter *
Sur un annuaire volumineux, cette commande retourne rapidement un grand nombre d’objets. Il est recommandé de la combiner avec Select-Object pour limiter l’affichage aux propriétés utiles :
Get-ADGroup -Filter * | Select-Object Name, GroupCategory, GroupScope
Filtrer les groupes AD par nom avec -Filter
Le paramètre -Filter accepte une syntaxe proche de PowerShell, ce qui permet de filtrer les groupes AD directement côté serveur, sans rapatrier inutilement l’ensemble de l’annuaire :
Get-ADGroup -Filter 'Name -like "GRP-*"'
Cette approche est nettement préférable à un filtrage avec Where-Object appliqué après coup, car ce dernier oblige le serveur Active Directory à transmettre tous les objets avant que PowerShell ne les trie localement. Filtrer directement avec -Filter réduit la charge réseau et accélère l’exécution, surtout sur un grand nombre de groupes.
Il reste possible de combiner les deux approches lorsque le critère recherché ne correspond à aucun attribut directement interrogeable via -Filter, par exemple pour appliquer une logique conditionnelle plus complexe sur les résultats déjà récupérés. Dans ce cas, il est recommandé de filtrer d’abord le plus largement possible côté serveur, puis d’affiner uniquement en local sur un ensemble déjà réduit :
Get-ADGroup -Filter 'Name -like "GRP-*"' -Properties Description |
Where-Object { $_.Description -match "Finance" }
Filtrer par catégorie ou étendue de groupe
Les propriétés GroupCategory et GroupScope permettent d’affiner la recherche selon le type de groupe recherché :
Get-ADGroup -Filter 'GroupCategory -eq "Security" -and GroupScope -eq "Global"'
Cette commande cible uniquement les groupes de sécurité à portée globale, en excluant les groupes de distribution ou les groupes à portée universelle ou locale de domaine.
Cibler une unité d’organisation avec -SearchBase
Le paramètre -SearchBase limite la recherche à une branche précise de l’annuaire, identifiée par son distinguished name. Il est particulièrement utile lorsque les groupes recherchés se trouvent dans une unité d’organisation dédiée :
Get-ADGroup -Filter * -SearchBase "OU=Groupes,OU=IT,DC=entreprise,DC=local"
Cette combinaison évite de parcourir l’intégralité du domaine lorsque seule une portion de l’arborescence est concernée, ce qui accélère nettement la recherche sur un grand annuaire.
Récupérer des propriétés supplémentaires avec -Properties
Par défaut, Get-ADGroup ne retourne qu’un nombre limité de propriétés. Le paramètre -Properties permet d’en récupérer d’autres, comme la description ou la date de création :
Get-ADGroup -Identity "GRP-Comptabilite" -Properties Description, whenCreated, ManagedBy
Utiliser -Properties * récupère l’ensemble des attributs disponibles, ce qui est utile pour explorer un objet groupe, mais alourdit inutilement la requête si seules quelques propriétés sont réellement nécessaires en usage courant.
Certaines propriétés fréquemment demandées ne sont pas incluses par défaut, comme ManagedBy (le gestionnaire du groupe), whenCreated (date de création) ou Members (liste brute des membres sous forme de distinguished names, moins pratique que Get-ADGroupMember pour un usage courant). Préciser explicitement les propriétés attendues plutôt que d’utiliser systématiquement -Properties * reste la pratique recommandée dans un script destiné à s’exécuter régulièrement.
Utiliser LDAPFilter pour des recherches avancées
Le paramètre -LDAPFilter permet d’exprimer la recherche directement sous forme de filtre LDAP, une syntaxe plus proche du fonctionnement natif de l’annuaire :
Get-ADGroup -LDAPFilter "(name=GRP-*)"
Ce paramètre est surtout pertinent pour des requêtes complexes déjà connues sous forme LDAP, ou lorsqu’une syntaxe précise n’est pas facilement transposable avec -Filter. Pour la majorité des besoins courants, -Filter reste plus lisible et suffisant.
Exporter les groupes Active Directory en CSV
Pour produire un export exploitable, il suffit de sélectionner les propriétés utiles avant de les transmettre à Export-Csv :
Get-ADGroup -Filter * -Properties Description |
Select-Object Name, GroupCategory, GroupScope, Description |
Export-Csv -Path "C:\Export\groupes_ad.csv" -NoTypeInformation -Encoding UTF8
L’option -NoTypeInformation évite l’ajout d’une ligne d’en-tête technique inutile dans le fichier, tandis que -Encoding UTF8 garantit un affichage correct des caractères accentués à l’ouverture du fichier CSV.
Pour un export limité à une seule unité d’organisation, il suffit d’ajouter -SearchBase à la commande précédente. Ce type d’export est couramment utilisé pour produire un inventaire des groupes Active Directory à destination d’un audit, d’une revue des droits ou d’une documentation d’infrastructure.
Get-ADGroup, Get-ADGroupMember et Get-ADPrincipalGroupMembership
Ces trois cmdlets sont souvent confondues alors qu’elles répondent à des questions différentes.
| Cmdlet | Ce qu’elle retourne | Exemple d’usage |
|---|---|---|
Get-ADGroup | Les propriétés du groupe lui-même | Rechercher ou lister des groupes |
Get-ADGroupMember | Les membres appartenant à un groupe donné | Lister les utilisateurs d’un groupe |
Get-ADPrincipalGroupMembership | Les groupes auxquels appartient un utilisateur ou un objet | Savoir dans quels groupes se trouve un compte |
Get-ADGroup ne renvoie jamais la liste des membres : pour cela, Get-ADGroupMember -Identity "GRP-Comptabilite" est nécessaire. À l’inverse, pour connaître les groupes Active Directory auxquels appartient un utilisateur précis, Get-ADPrincipalGroupMembership -Identity "jdupont" est la commande adaptée.
Erreurs fréquentes avec Get-ADGroup
Plusieurs erreurs reviennent régulièrement lors de l’utilisation de cette cmdlet :
- Module ActiveDirectory absent : la commande échoue si RSAT n’est pas installé ou si le module n’a pas été importé sur un poste qui n’est pas un contrôleur de domaine.
- Groupe introuvable : une erreur de frappe dans le nom transmis à
-Identity, ou une recherche limitée par un-SearchBasemal ciblé, empêche PowerShell Active Directory de localiser l’objet. - Syntaxe de filtre incorrecte : le paramètre
-Filterattend une syntaxe entre guillemets simples, avec des opérateurs comme-eqou-like; une syntaxe LDAP directement passée dans-Filterprovoque une erreur. - Droits insuffisants : un compte sans autorisation de lecture sur certaines unités d’organisation peut obtenir des résultats incomplets sans message d’erreur explicite, ce qui peut fausser silencieusement un export.
- Confusion entre -Filter et -LDAPFilter : mélanger la syntaxe des deux paramètres dans une même commande, ou tenter d’utiliser une syntaxe LDAP entre guillemets simples avec
-Filter, génère une erreur de syntaxe difficile à diagnostiquer pour un utilisateur peu familier des deux formats.
Bonnes pratiques pour interroger les groupes Active Directory
Filtrer directement côté serveur avec -Filter ou -SearchBase, plutôt que de rapatrier l’ensemble des groupes AD pour les trier ensuite en local, reste la pratique la plus efficace sur un grand annuaire. Limiter les propriétés demandées avec -Properties aux seuls attributs réellement nécessaires réduit également le temps de réponse des scripts d’administration s’exécutant régulièrement, notamment dans le cadre d’exports automatisés ou de tâches planifiées.
Documenter clairement, au sein même des scripts, quelle cmdlet est utilisée pour quel besoin facilite aussi la maintenance sur la durée : Get-ADGroup pour identifier ou lister des groupes, Get-ADGroupMember pour en connaître le contenu, et Get-ADPrincipalGroupMembership pour remonter les appartenances d’un compte donné. Cette distinction, une fois assimilée, évite la plupart des confusions rencontrées par les administrateurs découvrant le module PowerShell Active Directory.
