Строим отчет о членстве пользователей в группах AD: 4 проблемы в написании Powershell-скрипта

Билл Стюарт, scripting guru, в своей статье на WindowsITPro описывает те проблемы, с которыми ему пришлось столкнуться при написании Powershell-скрипта, который бы выводил членство пользователей в группах Active Directory. Пришлось проделать 4 усовершенствования, чтобы все заработало как надо. Узнать, как Билл реализовал таки вывод членства в группах, и скачать сам Powershell-скрипт Вы можете под катом.

Ссылка на окончательный вариант скрипта.
www.windowsitpro.com/content/content/141463/141463.zip

Я сбился со счету, сколько раз я уже встречал на форумах вопрос: “Кто-нибудь знает, как получить информацию обо всех пользователях и их членстве в группах в домене AD?”. Аудиторы и консультанты по информационной безопасности также задают подобный вопрос, когда осуществляют оценку инфраструктуры (среды) Active Directory в организации. Так как этот вопрос довольно насущный, я решил написать PowerShell скрипт, который бы позволял упростить эту задачу.
Сначала я думал, что написать подобный скрипт – пара пустяков, но на моем пути встретились 4 препятствия, которые усложнили мою работу. Я опишу эти проблемы, чуть позже, но сначала мне хотелось бы рассказать об основах использования Microsoft.NET в Powershell при поиске по AD.

Использование .NET для поиска по AD

Используя .NET для поиска по AD, Вы можете использовать type accelerator в PowerShell для поиска объектов. (Type accelerator – сокращенное имя для .NET класса). Например, введите следующую команду, чтобы вывести список всех пользователей в данном домене:

PS C:> $searcher =  "(&(objectCategory=user)(objectClass=user))"
 
PS C:> $searcher.FindAll()

[ ADSISearcher] – это type accelerator для объекта .NET System.DirectoryServices.DirectorySearcher. Строка, идущая после данного type accelerator, задает свойства SearchFilter для данного объекта, чтобы найти все объекты пользователей, и метод FindAll начинает поиск. На выходе мы получаем список объектов System.DirectoryServices.SearchResult.
Затем мы хотим определить, в какой группе состоит пользователь. Чтобы узнать, мы можем использовать коллекцию свойств (Properties collection) из объекта SearchResult и извлечь такой атрибут объекта как memberof. Используя переменную $searcher из предыдущего примера, мы можем использовать метод FindOne (вместо FindAll), чтобы извлечь один результат и вывести членство пользователя в группах:

PS C:> $result = $searcher.FindOne()
 
PS C:> $result.Properties["memberof"] | sort-object

Первая команда находит первого пользователя, который удовлетворяет поисковому фильтру, а вторая команда выводит список в групп, в которых пользователь состоит.
Однако если внимательно посмотреть на этот список, то можно заметить отсутствие важной детали: основная группа (primary group) пользователя не включена в атрибут memberof. Хотелось бы получить полный список групп (включая основную группу), что приводит нас к первой проблеме.

Проблема #1: Как найти основную группу пользователя

Есть обходной путь для исключения основной группы из атрибута memberof. Он описан в этой статье support.microsoft.com/kb/321360 Совершаем следующие действия:

1. Связываемся (connect to) с объектом пользователя, используя WinNT provider (вместо LDAP provider).
2. Извлекайте атрибут пользователя primaryGroupID .
3. Извлекайте имена групп пользователя, используя WinNT provider, который включает основную группу.
4. Осуществляйте поиск в AD этих групп, используях их sAMAccountName атрибуты.
5. Находим группу, в которой атрибут primaryGroupToken совпадает с атрибутом пользователя primaryGroupID.

Проблема с этим “обходным путем” заключается в том, что он требует, чтобы скрипт WinNT provider для подключения к объекту пользователя. То есть, необходимо, чтобы скрипт перевел различающееся имя пользователя (например, CN=Ken Myer,OU=Marketing,DC=fabrikam,DC=com) в формат, который WinNT provider может использовать (например, WinNT://FABRIKAM/kenmyer,User).

Проблема #2: Перевод из одного формата имени в другой

Объект NameTranslate является COM (ActiveX) объектом, который использует интерфейс IADsNameTranslate, осуществляющий перевод имен объектов AD в переменные (чередующиеся, alternate) форматы. Вы можете использовать объект NameTranslate, создав объект и затем вызвав его Init метод для инициализации. Например, список 1 показывает код VBScript скрипта, которые создает и инициализирует NameTranslate.

Список 1: Создание и инициализация объекта NameTranslate в VBScript

Const ADS_NAME_INITTYPE_GC = 3
 
Dim NameTranslate
 
Set NameTranslate = CreateObject("NameTranslate")
 
NameTranslate.Init ADS_NAME_INITTYPE_GC, vbNull

Однако объект NameTranslate не работает так, как ожидалось в PowerShell, что показано на рисунке 1.

Рис 1: Неожиданное поведения объекта NameTranslate в PowerShell

Проблема заключается в том, что в объекте NameTranslate отсутствует библиотека типов, которые .NET (а следовательно и PowerShell) использует для предоставление простого доступа к COM-объектам. Но к счастью и эту проблему можно обойти: метод .NET InvokeMember позволяет PowerShell получить или установить свойства или вызвать метод из COM-объекта, который отсутствует в библиотеке типов. Список 2 показывает Powershell эквивалент кода скрипта VBScript, приведенного в таблице 1

Список 2: Создание и инициализация объекта NameTranslate в PowerShell

$ADS_NAME_INITTYPE_GC = 3
 
$NameTranslate = new-object -comobject NameTranslate
 
[Void] $NameTranslate.GetType().InvokeMember("Init", "InvokeMethod",
 
  $NULL, $NameTranslate, ($ADS_NAME_INITTYPE_GC, $NULL))

Я хотел, чтобы скрипт решал другую проблему, связанную с именем. Атрибут memberof для пользователя AD содержит список различающихся имен, в которых пользователь состоит, но вместо этого я хотел получить атрибут samaccountname для каждой группы. Скрипт использует объект NameTranslate, чтобы справиться с этой проблемой.

Проблема #3: Что делать со специальными символами

Документация Microsoft относительно различающихся имен упоминает, что отдельные символы должны быть опущены (например, с префиксом “”) для того, чтобы быть правильным образом интерпретированы (в этой статье написано подробнее). К счастью, COM-объект Pathname дает такую возможность. Скрипт использует объект Pathname, чтобы пропустить те различающиеся имена, которые содержат специальные символы. Объект Pathname также требует .NET метод InvokeMember потому что, также как и объект NameTranslate, у этого объекта отсутствует библиотека типов.

Проблема #4: Повышаем производительность

Если оглянуться на Проблему #1 (Как найти основную группу пользователя), можно заметить, что обходное решение требует поиск групп пользователя. Проделав эту процедуру для нескольких учетных записей, Вы поймете, насколько она неоптимальна. Извлечение атрибута samaccountname для каждой группы в атрибуте memberof, о котором я упомянул, рассматривая Проблему #2 (Перевод из одного формата имени в другой) также неоптимально и отнимает много времени. Чтобы решить эту проблему скрипт использует две глобальные хеш-таблицы (global hash tables), которые производят хеширование результатов для повышения произодительности.

Get-UsersAndGroups.ps1

Get-UsersAndGroups.ps1 — это готовый Powershell-скрипт, который выводит список пользователей и их членства в группах. Синтаксис командной строки скрипта следующий:

 
Get-UsersAndGroups [[-SearchLocation] <String[]>] [-SearchScope <String>]

Параметр -SearchLocation представляет собой одно или несколько различающихся имен для учетных записей пользователей. Потому что различающееся имя содержит запятые (,), их необходимо помещать в скобки (одинарные или двойные) каждое различающееся имя, чтобы PowerShell не интерпретировал их как массив. Имя параметра -SearchLocation опционально. Скрипт также принимает конвейерный ввод (pipeline input); каждое значение из конвейера должно являться различающимся именем, которое необходимо искать.
Значение -SearchScope обозначает возможный масштаб поиска по AD. Это значение должно быть одним из трех: Base – Поиск ограничивается базовым объектом, не используется; OneLevel – поиск ближайших дочерних объектов базового объекта и Subtree – поиск по подветке. Если это значение не уточнено, то по умолчанию используется Subtree. Используйте -SearchScope OneLevel, если Вы хотите определенное подразделение (OU), но ни одна из OU не вложена в него. Скрипт выводит объекты, которые содержат свойства, перечисленные в таблице 1.

Преодолевая 4 проблемы

Скрипт решает вышеописанные проблемы:

• Проблема #1: Как найти основную группу пользователя: Функция get-primarygroupname возвращает имя основной группы пользователя.
• Проблема #2: Перевод из одного формата имени в другой: Скрипт использует COM-объект NameTranslate, чтобы осуществить перевод из одного формата имени в другое.
• Проблема #3: Что делать со специальными символами: Скрипт использует функцию get-escaped, которая использует объект Pathname, чтобы возвратить различающиеся имена с вставленными пропущенными символами (там, где это необходимо).
• Проблема #4: Повышаем производительность: Скрипт использует хэш-таблицы $PrimaryGroups и $Groups. Ключи в хеш-таблице $PrimaryGroups являютяются идентификаторами основной группы и их значения – атрибутами samaccountname основной группы.

Упрощаем аудит групп и пользователей

Написание скрипта Get-UsersAndGroups.ps1 оказалось не таким уж и простым, как мне казалось с первого взгляда, но проще сделать нельзя. Простейшее приложение скрипта –следующая команда:

PS C:> Get-UsersAndGroups | Export-CSV Report.csv -NoTypeInformation

Она создает .csv файл, который содержит полный список пользователей и групп для данного домена. Имя в своем арсенале такой скрипт, мы можете быстро и без проблем создать отчет по группам и пользователям.

Еще раз продублируем ссылку на окончательный вариант скрипта.
www.windowsitpro.com/content/content/141463/141463.zip

Сам скрипт:

# Get-UsersAndGroups.ps1
# Written by Bill Stewart (bstewart@iname.com)

#requires -version 2

<#
.SYNOPSIS
Retreves users, and group membership for each user, from Active Directory.

.DESCRIPTION
Retreves users, and group membership for each user, from Active Directory. Note that each user's primary group is included in the output, and caching is used to improve performance.

.PARAMETER SearchLocation
Distinnguished name (DN) of where to begin searching for user accounts; e.g. "OU=Information Technology,DC=fabrikam,DC=com". If you omit this parameter, the default is the current domain (e.g., "DC=fabrikam,DC=com").

.PARAMETER SearchScope
Specifies the scope for the Active Directory search. Must be one of the following values: Base (Limit the search to the base object, not used), OneLevel (Searches the immediate child objects of the base object), or Subtree (Searches the whole subtree, including the base object and all its child objects). The default value is Subtree. To search only a location but not its children, specify OneLevel.

.OUTPUTS
PSObjects containing the following properties:
  DN        The user's distinguished name
  CN        The user's common name
  UserName  The user's logon name
  Disabled  True if the user is disabled; false otherwise
  Group     The groups the user is a member of (one object per group)
#>

[CmdletBinding()]
param(
  [parameter(Position=0,ValueFromPipeline=$TRUE)]
    [String[]] $SearchLocation="",
    [String][ValidateSet("Base","OneLevel","Subtree")] $SearchScope="Subtree"
)

begin {
  $ADS_NAME_INITTYPE_GC = 3
  $ADS_SETTYPE_DN = 4
  $ADS_NAME_TYPE_1779 = 1
  $ADS_NAME_TYPE_NT4 = 3
  $ADS_UF_ACCOUNTDISABLE = 2

  # Assume pipeline input if SearchLocation is unbound and doesn't exist.
  $PIPELINEINPUT = (-not $PSBOUNDPARAMETERS.ContainsKey("SearchLocation")) -and (-not $SearchLocation)
  # If -SearchLocation is a single-element array containing an emty string
  # (i.e., -SearchLocation not specified and no pipeline), then populate with
  # distinguished name of current domain. In this case, input is not coming
  # from the pipeline.
  if (($SearchLocation.Count -eq 1) -and ($SearchLocation[0] -eq "")) {
    try {
      $SearchLocation[0] = ([ADSI] "").distinguishedname[0]
    }
    catch [System.Management.Automation.RuntimeException] {
      throw "Unable to retrieve the distinguished name for the current domain."
    }
    $PIPELINEINPUT = $FALSE
  }

  # These hash tables cache primary groups and group names for performance.
  $PrimaryGroups = @{}
  $Groups = @{}

  # Create and initialize a NameTranslate object. If it fails, throw an error.
  $NameTranslate = new-object -comobject "NameTranslate"

  try {
    [Void] $NameTranslate.GetType().InvokeMember("Init", "InvokeMethod", $NULL, $NameTranslate, ($ADS_NAME_INITTYPE_GC, $NULL))
  }
  catch [System.Management.Automation.MethodInvocationException] {
    throw $_
  }

  # Create a Pathname object.
  $Pathname = new-object -comobject "Pathname"

  # Returns the last two elements of the DN using the Pathname object.
  function get-rootname([String] $dn) {
    [Void] $Pathname.GetType().InvokeMember("Set", "InvokeMethod", $NULL, $Pathname, ($dn, $ADS_SETTYPE_DN))
    $numElements = $Pathname.GetType().InvokeMember("GetNumElements", "InvokeMethod", $NULL, $Pathname, $NULL)
    $rootName = ""
    ($numElements - 2)..($numElements - 1) | foreach-object {
      $element = $Pathname.GetType().InvokeMember("GetElement", "InvokeMethod", $NULL, $Pathname, $_)
      if ($rootName -eq "") {
        $rootName = $element
      }
      else {
        $rootName += ",$element"
      }
    }
    $rootName
  }

  # Returns an "escaped" copy of the specified DN using the Pathname object.
  function get-escaped([String] $dn) {
    [Void] $Pathname.GetType().InvokeMember("Set", "InvokeMethod", $NULL, $Pathname, ($dn, $ADS_SETTYPE_DN))
    $numElements = $Pathname.GetType().InvokeMember("GetNumElements", "InvokeMethod", $NULL, $Pathname, $NULL)
    $escapedDN = ""
    for ($n = 0; $n -lt $numElements; $n++) {
      $element = $Pathname.GetType().InvokeMember("GetElement", "InvokeMethod", $NULL, $Pathname, $n)
      $escapedElement = $Pathname.GetType().InvokeMember("GetEscapedElement", "InvokeMethod", $NULL, $Pathname, (0, $element))
      if ($escapedDN -eq "") {
        $escapedDN = $escapedElement
      }
      else {
        $escapedDN += ",$escapedElement"
      }
    }
    $escapedDN
  }

  # Return the primary group name for a user. Algorithm taken from
  # http://support.microsoft.com/kb/321360
  function get-primarygroupname([String] $dn) {
    # Pass DN of user to NameTranslate object.
    [Void] $NameTranslate.GetType().InvokeMember("Set", "InvokeMethod", $NULL, $NameTranslate, ($ADS_NAME_TYPE_1779, $dn))
    # Get NT4-style name of user from NameTranslate object.
    $nt4Name = $NameTranslate.GetType().InvokeMember("Get", "InvokeMethod", $NULL, $NameTranslate, $ADS_NAME_TYPE_NT4)
    # Bind to user using ADSI's WinNT provider and get primary group ID.
    $user = [ADSI] "WinNT://$($nt4Name.Replace('', '/')),User"
    $primaryGroupID = $user.primaryGroupID[0]
    # Retrieve user's groups (primary group is included using WinNT).
    $groupNames = $user.Groups() | foreach-object {
      $_.GetType().InvokeMember("Name", "GetProperty", $NULL, $_, $NULL)
    }
    # Query string is sAMAccountName attribute for each group.
    $queryFilter = "(|"
    $groupNames | foreach-object { $queryFilter += "(sAMAccountName=$($_))" }
    $queryFilter += ")"
    # Build a DirectorySearcher object.
    $searchRootDN = get-escaped (get-rootname $dn)
    $searcher = [ADSISearcher] $queryFilter
    $searcher.SearchRoot = [ADSI] "LDAP://$searchRootDN"
    $searcher.PageSize = 128
    $searcher.SearchScope = "Subtree"
    [Void] $searcher.PropertiesToLoad.Add("samaccountname")
    [Void] $searcher.PropertiesToLoad.Add("primarygrouptoken")
    # Find the group whose primaryGroupToken attribute matches user's
    # primaryGroupID attribute.
    foreach ($searchResult in $searcher.FindAll()) {
      $properties = $searchResult.Properties
      if ($properties["primarygrouptoken"][0] -eq $primaryGroupID) {
        $groupName = $properties["samaccountname"][0]
        return $groupName
      }
    }
  }

  # Return a DN's sAMAccount name based on the distinguished name.
  function get-samaccountname([String] $dn) {
    # Pass DN of group to NameTranslate object.
    [Void] $NameTranslate.GetType().InvokeMember("Set", "InvokeMethod", $NULL, $NameTranslate, ($ADS_NAME_TYPE_1779, $dn))
    # Return the NT4-style name of the group without the domain name.
    $nt4Name = $NameTranslate.GetType().InvokeMember("Get", "InvokeMethod", $NULL, $NameTranslate, $ADS_NAME_TYPE_NT4)
    $nt4Name.Substring($nt4Name.IndexOf("") + 1)
  }

  function get-usersandgroups2($location) {
    # Finds user objects.
    $searcher = [ADSISearcher] "(&(objectCategory=User)(objectClass=User))"
    $searcher.SearchRoot = [ADSI] "LDAP://$(get-escaped $location)"

    # Setting the PageSize property prevents limiting of search results.
    $searcher.PageSize = 128
    $searcher.SearchScope = $SearchScope

    # Specify which attributes to retrieve ([Void] prevents output).
    [Void] $searcher.PropertiesToLoad.Add("distinguishedname")
    [Void] $searcher.PropertiesToLoad.Add("cn")
    [Void] $searcher.PropertiesToLoad.Add("samaccountname")
    [Void] $searcher.PropertiesToLoad.Add("useraccountcontrol")
    [Void] $searcher.PropertiesToLoad.Add("primarygroupid")
    [Void] $searcher.PropertiesToLoad.Add("memberof")
    # Sort results by CN attribute.
    $searcher.Sort = new-object System.DirectoryServices.SortOption
    $searcher.Sort.PropertyName = "cn"

    foreach ($searchResult in $searcher.FindAll()) {
      $properties = $searchResult.Properties
      $dn = $properties["distinguishedname"][0]
      write-progress "Get-UsersAndGroups" "Searching $location" -currentoperation $dn
      $cn = $properties["cn"][0]
      $userName = $properties["samaccountname"][0]
      $disabled = ($properties["useraccountcontrol"][0] -band $ADS_UF_ACCOUNTDISABLE) -ne 0
      # Create an ArrayList containing user's group memberships.
      $memberOf = new-object System.Collections.ArrayList
      $primaryGroupID = $properties["primarygroupid"][0]
      # If primary group is already cached, add the name to the array;
      # otherwise, find out the primary group name and cache it.
      if ($PrimaryGroups.ContainsKey($primaryGroupID)) {
        [Void] $memberOf.Add($PrimaryGroups[$primaryGroupID])
      }
      else {
        $primaryGroupName = get-primarygroupname $dn
        $PrimaryGroups.Add($primaryGroupID, $primaryGroupName)
        [Void] $memberOf.Add($primaryGroupName)
      }
      # If the user's memberOf attribute is defined, find the group names.
      if ($properties["memberof"]) {
        foreach ($groupDN in $properties["memberof"]) {
          # If the group name is aleady cached, add it to the array;
          # otherwise, find out the group name and cache it.
          if ($Groups.ContainsKey($groupDN)) {
            [Void] $memberOf.Add($Groups[$groupDN])
          }
          else {
            $groupName = get-samaccountname $groupDN
            $Groups.Add($groupDN, $groupName)
            [Void] $memberOf.Add($groupName)
          }
        }
      }
      # Sort the ArrayList and output one object per group.
      $memberOf.Sort()
      foreach ($groupName in $memberOf) {
        $output = new-object PSObject
        $output | add-member NoteProperty "DN" $dn
        $output | add-member NoteProperty "CN" $cn
        $output | add-member NoteProperty "UserName" $userName
        $output | add-member NoteProperty "Disabled" $disabled
        $output | add-member NoteProperty "Group" $groupName
        $output
      }
    }
  }
}

process {
  if ($PIPELINEINPUT) {
    get-usersandgroups2 $_
  }
  else {
    $SearchLocation | foreach-object {
      get-usersandgroups2 $_
    }
  }
}

via WindowsITPro

P.S. Для получения разнообразных отчетов по структуре и изменениям AD Вы можете воспользоваться NetWrix AD Change Reporter. Программа позволяет Вам быть в курсе изменений AD и при этом не требует от Вас утомительной работы с логами или ручной автоматизации посредством скриптов. Узнать больше о программе Вы сможете на сайте NetWrix

Автор: NetWrixRU