Модуль сценария ADT "CM_ActiveDirectory"

#===============<Модуль ActiveDirectory: константы>===============

#Код ошибки "Подразделение AD с заданным именем уже существует"
Set-Constant -Name "SYSTEM_ERROR_CODE_OU_ALREADY_EXISTS" -Value -2147019886

#------Код ошибки: объект с заданным именем уже существует.
Set-Constant -Name "SYSTEM_ERROR_CODE_OU_ALREADY_EXISTS"  -Value -2147019886
Set-Constant -Name "SYSTEM_ERROR_CODE_GPO_LINK_ALREADY_EXISTS"  -Value "0x800700B7"

#===============</Модуль ActiveDirectory: константы>===============

#------Псевдодимы разрешений (прав доступа) к объектам групповых политик.
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_READ" -Value   "read"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_EDIT" -Value           "edit"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_APPLY"  -Value "Apply Group Policy"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_FULL_EDIT"  -Value     "fulledit"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_NONE"   -Value         "none"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_WRITE"  -Value         "Write"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_CREATE_ALL_CHILD_OBJECT"    -Value     "Create All Child Object"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_DELETE_ALL_CHILD_OBJECT"    -Value     "Delete All Child Object"
Set-Constant -Name "SYSTEM_AD_GPO_PERMISSION_FULL_CONTROL"   -Value     "Full Control"


#===============<Модуль ActiveDirectory: функции>==================

<#
.SYNOPSIS
    Принимает путь к OU в формате "example.com/123/456", возвращает его Distinguished Name.

.Description
    Корректность пути и его существование не проверяется, что позвоялет использовать функцию
    для несуществующих путей.
    ВНИМАНИЕ: имя домена должно быть полным DNS-именем, а не NEIBIOS именем (т.е. example.com, а не EXAMPLE)

.PARAMETER Path
    Путь, который будет сконвертирован в DN

.OUTPUTS
    System.String. Возвращает Distinguished Name, соответствующий переданному пути.
#>
Function Convert-ADPath2DN([STRING]$Path)
{   $Res = ""
    $ResOU = $null
    #Преобразуем путь к OU в OU DN
    $P = Join-Path $Path "/"
    $P = $P.Replace("\","/")
    #Проверяем, получилось ли у нас что-то похожее на путь
    if ($P -match "^(?<DNS_DOMAIN_NAME>(\w+\.\w+)+)\/.+$")
    {


        $i = 0
        $DNS_DOMAIN_NAME = $Matches.DNS_DOMAIN_NAME
        #Формируем путь по OU
        While (-not ($P -eq $DNS_DOMAIN_NAME))
        {
            $i++
            $OU = Split-Path -Leaf $P
            $P = Split-Path -Parent $P
            If ($i -ne 1)
            {
                $ResOU = $ResOU + ","
            }
            $ResOU = $ResOU+ "OU=$OU"
        }
    }
    else
    {
        $DNS_DOMAIN_NAME = [System.DirectoryServices.ActiveDirectory.Domain]::GetCurrentDomain().Name
    }

    #Меняем точки на слэши, чтобы модно было использовать удобные функции для работы с путями
    $DNS_DOMAIN_NAME = $DNS_DOMAIN_NAME.Replace(".","\")


    $DC_NAMES = @()
    While ($DNS_DOMAIN_NAME -ne "")
    {
        $DC = Split-Path -Leaf $DNS_DOMAIN_NAME
        $DNS_DOMAIN_NAME = Split-Path -parent $DNS_DOMAIN_NAME
        $DC_NAMES = $DC_NAMES + $DC
    }



    $Count = $DC_NAMES.Count
    for ($i=$Count;$i -gt 0;$i--)
    {
        $DC = $DC_NAMES[$i - 1]
        If ($i -ne $Count)
        {
            $ResDC = $ResDC + ","
        }
        $ResDC = $ResDC+ "DC=$DC"
        if ($ResOU -ne $null)
        {
            $Res = $ResOU + "," + $ResDC
        }
        else
        {
            $Res = $ResDC
        }
    }

    Return $Res
}

<#
.SYNOPSIS
    Создает подразделение организации в AD с заданным именем по заданному пути.
.Description
    При создании подразделения существование родителя не проверяется, что может вызвать проблемы.
    Эта функция - служебная. Для создания подразделений рекомендуется использовать функцию
    New-ADOrganizationUnit

.PARAMETER Path
    Путь к подразделению AD, в котором будем создавать OU (т.е. родителю).

.PARAMETER Name
    Имя создаваемого подразделения (Organization Unit).

.OUTPUTS
    $null. Функция не возвращает значений.
#>
Function New-ADOrganizationUnit_simple([STRING]$Path,[STRING]$Name)
{
    #Отключаем сообщения об исключениях, т.к. они будут возникать довольно часто.
    #основная причина - попытка создать OU, который уже существует.
    $ErrorActionPreference = "SilentlyContinue"

    #Конвертируем путь в нотацию DN (см. описание функции выше)
    $OUDN = Convert-ADPath2DN -Path $Path

    #Приводим путь к стандарту ADsPath
    $OUDN = "LDAP://$OUDN"

    #Создаем объект, представляющий текущий домен
    $objDomain = [ADSI]$OUDN

    #Создаем подразделение
    $objOU = $objDomain.Create("organizationalUnit", "ou=$Name")
    $objOU.SetInfo()

    #Обработка исключений
    Trap
    {
        #Если дело в том, что такое подразделение уже есть, оповестим об этом пользователя.
        if ($_.Exception.ErrorCode -eq $SYSTEM_ERROR_CODE_OU_ALREADY_EXISTS)
        {
            Write-Host "OU $Name в $Path уже существует"
        }
    }

}

<#
.SYNOPSIS
    Создает подразделение организации в AD по заданному пути.

.Description
    Будет создан не только последний элемент, но и вся родительская иерархия (все родительские подразделения).

.PARAMETER Path
    Путь к создаваемому подразделению.

.OUTPUTS
    $null. Функция не возвращает значений.
#>
Function New-ADOrganizationUnit ([STRING]$Path)
{
    #Проверяем, соответствует ли переданная строка пути к подразделению (example.com/Unit1/Unit2...)
    If ($Path -match "^(?<DNS_DOMAIN_NAME>(\w+\.\w+)+)\/.+$")
    {
        $i = 0
        #Меняем направление слешей, чтобы использовать командлеты "*-Path"
        $Pth = Join-Path $Path "/"
        $Pth = $Pth.Replace("\","/")

        $OUs = @()
        #Создаем OU по одному
        While ($Pth -ne "")
        {
            $i++
            $Pos = $Pth.IndexOf("/")

            If ($i -eq 1)
            {
                $DNS_DOMAIN_NAME = $Pth.Substring(0,$Pos)
            }
            else
            {
                $OU = $Pth.Substring(0,$Pos)
                $OUs = $OUs + $OU
            }
            $Pth = $Pth.Substring($Pos+1,($Pth.Length - $Pos -1))
        }

        #Создаем весь путь OU
        $Pth = $DNS_DOMAIN_NAME
        For ($i=0;$i -lt $OUs.Count;$i++)
        {
            $OU = $OUs[$i]
            #Вызываем предыдущу функцию для непосредственного создания OU.
            #Подразделения создаются "сверху вниз", поэтому ситуация создания
            #дочернего подразделения при отсутствии родительского - исключена.
            New-ADOrganizationUnit_simple -Name $OU -Path $Pth
            $Pth = $Pth + "/" + $OU

        }
    }
}

<#
.SYNOPSIS
    Создает группу AD в заданном OU.

.Description
    Создает глобальную группу безопасности в заданном подразделении организации (Organization Unit).

.PARAMETER Path
    Путь к подразделению организации, в котором нужно создать группу.

.PARAMETER Name
    Имя создаваемой группы

.PARAMETER Force
    Модификатор создания пути. Если он задан, то путь к OU будет принудительно создан.

.OUTPUTS
    $null. Данная функция не возвращает значений.
#>
Function New-ADGroup([STRING]$Path, [STRING]$Name, [System.Management.Automation.SwitchParameter]$Force)
{
    #Если указано, принудительно создаём иерархию подразделений
    $ErrorActionPreference = "SilentlyContinue"
    If ($Force -eq $true)
    {
        New-ADOrganizationUnit -Path $Path
    }
    #Конвертируем понятное неспециалисту представление пути в DN
    $OUDN = Convert-ADPath2DN -Path $Path

    #Создаем объект - представление домена
    $OUDN = "LDAP://$OUDN"
    $OU = [ADSI]"$OUDN"

    #Создаем и сохраняем группу безопасности в подразделении
    $Group = $OU.Create("group", "cn=$Name")
    $Group.Put("sAMAccountName", "$Name")
    $Group.SetInfo()

    #Обработка исключений
    Trap
    {
        #Наиболее часто возникающее исключение, не требующее остановки:
        # "такая группа уже существует"
        if ($_.Exception.ErrorCode -eq $SYSTEM_ERROR_CODE_OU_ALREADY_EXISTS)
        {
            Write-Host "Группа $Name в $Path уже существует"
        }
    }
}

<#
.SYNOPSIS
    Позволяет определить GUID резервной копии GPO по её (копии) содержимому.

.Description
    Функция просматривает список дочерних папок в резервной копии GPO, находит среди них папку, имя которой - GUID, и
    возвращает это значение в качестве GUID'а резервной копии. Идея метода в том, что корректная резервная копия GPO
    содержит одну папку с именем в виде GUID'а. Этот имя этой папки - всегда соответствует GUID'у резервной копии.

.PARAMETER Path
    Path - путь к папке, в которой находится резервная копия GPO.

.OUTPUTS
    System.String. GUID резервной копии GPO, расположенной по заданному пути.
#>
Function Get-ExportedBackupGUID([STRING]$Path)
{
    #Проверяем, доступна ли указанная папка, если нет - выбрасываем исключение
    If (-not (Test-Path $Path))
    {
        Write-Host "Папки $Path не существует"
        Throw "Backup dir path not found"
    }

    #Получаем список подпапок
    $Children = Get-ChildItem -Force -LiteralPath $Path

    #Ищем в среди подпапок ту, которая именована GUID'ом
    Foreach ($Child in $Children)
    {
        If ($Child.FullName -match "^*\{\w{8}\-(\w{4}\-){3}\w{12}\}$")
        {
            Return $Matches[0]
        }

    }
    #Папка доступна, но резервных копий GPO в ней нет.
    Write-Host "В папке $Path не найдены резервные копии политик"
    Throw "GPO Backup(s) not found"
}

<#
.SYNOPSIS
    Создает новый объект групповой политики в заданном домене.

.Description
    Привязка созданного объекта к подразделению организации не выполняется.  Для работы используется
    COM-объект GPMC (соответственно, GPMC должна быть установлена).

.PARAMETER DomainDNSName
    FQDN-имя домена, в котором будет создан объект групповой политики.

.PARAMETER GPOName
    Имя создаваемого объекта групповой политики.

.OUTPUTS
    GPMGPO. Возвращает созданный объект групповой политики.
#>
Function New-GPO([STRING]$DomainDNSName,[STRING]$GPOName)
{
    $GPM = New-Object -ComObject GPMgmt.GPM
    #Список предопределенных констант
    $GPMConstants = $GPM.GetConstants()
    #Объект домена
    $GPMDomain = $GPM.GetDomain($DNS_DOMAIN_NAME, $DNS_DOMAIN_NAME, $Constants.UseAnyDC)
    #Создаем GPO
    $GPMGPO = $GPMDomain.CreateGPO()
    $GPMGPO.DisplayName = $GPOName

    Return $GPMGPO
}

<#
.SYNOPSIS
    Получает COM-объект заданной GPO по её имени.

.Description
    Позволяет получить пригодный для модификации объект GPO, зная её имя.

.PARAMETER DomainDNSName
    FQDN-имя домена, в котором выполняется поиск GPO.

.PARAMETER GPOName
    Имя GPO, который нужно найти.

.OUTPUTS
    GPMGPO. Возвращает ссылку на COM-объект найденной GPO ( или $null, если GPO не была найдена).
#>
Function Get-GPO([STRING]$DomainDNSName,[STRING]$GPOName)
{
    $GPMGPO = $null
    #Отключаем реакции на возникающие исключения
    $ErrorActionPreference = "SilentlyContinue"

    #Создаем объект, представляющий GPMC
    $GPM = New-Object -ComObject GPMgmt.GPM

    #Список предопределенных констант
    $GPMConstants = $GPM.GetConstants()

    #Получаем объект GPMDomain, представляющий текущий домен
    $GPMDomain = $GPM.GetDomain($DomainDNSNAme, $DomainDNSNAme, $GPMConstants.UseAnyDC)

    #Ищем групповую политику в домене по её имени
    $GPMGPO = $GPMDomain.SearchGPOs($GPM.CreateSearchCriteria()) | Where-Object{$_.DisplayName -eq $GPOName}

    #Возвращаем объект GPO. Если политика не найдена - вернется $null.
    Return $GPMGPO
}

<#
.SYNOPSIS
    Импортирует настройки GPO из резервной копии.

.Description
    Позволяет импортировать в заданный объект групповой политики настройки, сохраненные в виде резервной копии объетка GPO.
    Речь идет именно об импрорте, а не восстановлении из резервной копии, поэтому допускается загрузка параметров из любого GPO.
    Если целевого объекта GPO не существует, он будет создан.

.PARAMETER  BackupPath
    Путь к папке с резервной копией GPO

.PARAMETER  DNS_DOMAIN_NAME
    FQDN-имя домена, в котором находится целевая политика (реципиент).

.PARAMETER  MigrationTablePath
    Не используется. Зарезервировано для будущих версий.

.PARAMETER  NewGPOName
    Имя объекта групповой политики, в который нужно загрузить настройки из резервной копии. Если этот параметр не указан, имя будет взято из
    резервной копии (т.е. параметры будут загружены в GPO с тем же именем, которое было у оригианльного GPO-донора).

.OUTPUTS
    $null. Функция не возвращает значений.
#>
Function Import-GPO ([STRING]$BackupPath, [STRING]$DNS_DOMAIN_NAME, [STRING]$MigrationTablePath, [STRING]$NewGPOName = "")
{
    #Проверяем доступность папки с резервной копией GPO. Если она недоступна, выбрасываем исключение
    If (-not (Test-Path $BackupPath))
    {
        Write-Host "Неверно указана папка с архивом GPO: $BackupPath"
        Throw "GPO Backup path not found"
    }

    #Получаем COM-объект GPMC - представление домена
    $GPM = New-Object -ComObject GPMgmt.GPM
    $GPMConstants = $GPM.GetConstants()
    $GPMDomain = $GPM.GetDomain($DNS_DOMAIN_NAME, $DNS_DOMAIN_NAME, $Constants.UseAnyDC)

    #Получаем объект GPMBackupDir, представляющий папку с резервной копией
    $GPMBackupDir = $GPM.GetBackupDir($BackupPath)
    #Определяем GUID экспортированной GPO
    $BackupGUID = Get-ExportedBackupGUID -Path $BackupPath
    #Получаем объект - представление экспортированного GPO
    $GPMBackup = $GPMBackupDir.GetBackup($BackupGUID)

    #Имя GPO, в которую будем импортировать настройки: если не указано, импортируем в объект с
    #тем же именем, которое имеет резервная копия
    If ($NewGPOName -eq "")
    {
        $TargetGPOName = $GPMBackup.GPODisplayName
    }
    else
    {
        $TargetGPOName = $NewGPOName
    }

    #Находим в репозитории объект GPO, в который будем импортировать настройки
    $GPMGPO = Get-GPO -DomainDNSNAme $DNS_DOMAIN_NAME -GPOName $TargetGPOName

    #Если GPO с заданным именем не нашелся, создаем его
    If ($GPMGPO -eq $Null)
    {
        $GPMGPO = New-GPO  -DomainDNSNAme $DNS_DOMAIN_NAME -GPOName $TargetGPOName
    }

    #Импортируем содержимое GPO
    $GPMGPO.Import(0, $GPMBackup) | Out-Null
}


<#
.SYNOPSIS
    Выполняет присоединение (Link) объекта групповой политики к заданному подразделению организации (OU).

.Description
    Присоединяет существующий объект GPO к существующему подразделению организации в рамках одного домена.
    Кросс-доменное присоединение не поддерживается.

.PARAMETER  DomainDNSName
    FQDN-имя домена, в котором выполняется операция присоединения.

.PARAMETER  GPOName
    Имя присоединяемого объекта GPO. Объект должен быть доступен в репозитории объектов групповых политик заданного домена.

.PARAMETER  OUPath
    Путь к подразделению организации, к которому нужно присоединить заданный объект GPO.

.OUTPUTS
    $Null. Данная функция не возвращает результат.
#>
Function Mount-GPOToOU ([STRING]$GPOName,[STRING]$OUPath,[STRING]$DomainDNSName)
{
    #Ищем нужный объект GPO в репозитории домена
    $GPMGPO = Get-GPO -DomainDNSName $DomainDNSName -GPOName $GPOName

    #Убеждаемся в том, что объект найден
    If ($GPMGPO -ne $Null)
    {
        #Приводим путь к нотации DN
        $OUDN = Convert-ADPath2DN -Path $OUPath

        #Получаем представление домена в виде COM-объекта GPMC
        $GPM = New-Object -ComObject GPMgmt.GPM
        $GPMConstants = $GPM.GetConstants()
        $GPMDomain = $GPM.GetDomain($DomainDNSName, $DomainDNSName, $Constants.UseAnyDC)

        #Получаем представление интересующего подразделения
        $GPMSOM = $GPMDomain.GetSOM($OUDN)

        $ErrorActionReference = "SilentlyContinue"

        #Выполняем привязку (Link) объекта GPO к подразделению
        $GPMSOM.CreateGPOLink(-1, $GPMGPO) | Out-Null

        $ErrorActionReference = "Continue"
        trap
        {
            #Исключения создаются внутри COM-объекта. У нас нет возможности определять их причину.
            #Как правило, она заключается в том, что указанный линк уже существует. Поэтому продолжаем
            continue
        }

    }
    #Если объект GPO по заданному имени не найден, сообщаем пользователю и выбрасываем исключение
    else
    {
        Write-Host "Cannot find a GPO object named $GPOName"
        Throw "Cannot_find_GPO"
    }
}


<#
.SYNOPSIS
    Позволяет получить доменно-зависимый компонент SID
.Description
    SID многих стандартных участников безопасности включает в себя т.н. доменный компонент, отличающийся
    у разных доменов. Данная функция позволяет получить его для текущего домена.
.OUTPUTS
    System.Security.Principal.SecurityIdentifier. SID текущего домена.
#>
Function Get-DomainSID()
{
    $domain = [ADSI]""
    $DomainSID = New-Object System.Security.Principal.SecurityIdentifier  ($Domain.objectSid.Value,0)
    Return $DomainSID
}

<#
.SYNOPSIS
    Пытается преобразовать заданную строку в Well-Known SID.

.Description
    Использует конструктор класса ystem.Security.Principal.WellKnownSidType для создания SID на основе заданной строки.
    Написана для удобства перехвата исключений.

.PARAMETER  $Name
    Строковое стандартного участника безопасности.

.OUTPUTS
    System.Security.Principal.WellKnownSidType или $null. Возвращает объект типа System.Security.Principal.WellKnownSidType,
    соответствующий переданной строке или $null (если строке не соотвтествует ни один объект указанного типа).
#>
Function Convert-ToSIDType([STRING]$Name)
{
    $Res = $null
    $ErrorActionPreference = "SilentlyContinue"
    $Res = [System.Security.Principal.WellKnownSidType]::$Name
    $ErrorActionPreference = "Stop"
    Return $Res
}

<#
.SYNOPSIS
    Получает тип SID стандартных усатников безопасности.

.Description
    Позволяет получить SID стандартных участников безопасности по имени / типу. Понимает константы
    $SYSTEM_AD_STD_GROUP_NAME_*, а так же имена типов перечисления System.Security.Principal.WellKnownSidType

.PARAMETER  Name
    Имя стандартного участника безопасности, SID которого нужно получить.

.OUTPUTS
    System.Security.Principal.WellKnownSidType. SID заданного участника безопасности
#>
Function Get-WellKnownSIDFromName([STRING]$Name)
{
    #------Псевдонимы стандарных субъектов безопасности
    $SYSTEM_AD_STD_GROUP_NAME_DOMAIN_ADMINS     =   "Domain Admins"
    $SYSTEM_AD_STD_GROUP_NAME_ENTERPRISE_ADMINS = "Enterprise Admins"
    $SYSTEM_AD_STD_GROUP_NAME_ENTERPRISE_DOMAIN_CONTROLLERS = "Enterprise Domain Controllers"
    $SYSTEM_AD_STD_GROUP_NAME_SYSTEM    =   "System"
    $SYSTEM_AD_STD_GROUP_NAME_AUTHENTICATED_USERS   =   "Authenticated Users"
    $SYSTEM_AD_STD_GROUP_NAME_DOMAIN_ADMIN  =   "Domain Administrator"
    $SYSTEM_AD_STD_GROUP_NAME_CREATOR_OWNERS    =   "Creator Owners"
    $DomainSID = Get-DomainSID
    Switch ($Name)
    {
        $SYSTEM_AD_STD_GROUP_NAME_DOMAIN_ADMINS
        {
            #Администраторы домена (Группа)
            #$SID = $DomainSID.value + "-512"
            $SIDType = [System.Security.Principal.WellKnownSidType]::AccountDomainAdminsSid
        }

        $SYSTEM_AD_STD_GROUP_NAME_ENTERPRISE_ADMINS
        {
            #$SID = $DomainAdminsGroupSID = $DomainSID.value + "-519"
            $SIDType = [System.Security.Principal.WellKnownSidType]::AccountEnterpriseAdminsSid
        }

        $SYSTEM_AD_STD_GROUP_NAME_CREATOR_OWNERS
        {
            #$SID = $DomainAdminsGroupSID = $DomainSID.value + "-520"
            $SIDType = [System.Security.Principal.WellKnownSidType]::CreatorOwnerSid
        }

        $SYSTEM_AD_STD_GROUP_NAME_ENTERPRISE_DOMAIN_CONTROLLERS
        {
            #$SID = "S-1-5-9"
            $SIDType = [System.Security.Principal.WellKnownSidType]::EnterpriseControllersSid
        }

        $SYSTEM_AD_STD_GROUP_NAME_SYSTEM
        {
            #$SID = "S-1-5-18"
            $SIDType = [System.Security.Principal.WellKnownSidType]::LocalSystemSid
        }

        $SYSTEM_AD_STD_GROUP_NAME_AUTHENTICATED_USERS
        {
            #$SID = "S-1-5-11"
            $SIDType = [System.Security.Principal.WellKnownSidType]::AuthenticatedUserSid
        }

        default
        {
            #$SID = $null
            $SIDType = $null
            $SIDType = Convert-ToSIDType -Name $Name
        }

    }
    Return $SIDType

}

<#
.SYNOPSIS
    Создает объект типа System.DirectoryServices.ActiveDirectoryRights по его имени.

.Description
    Использует стандартный конструктор класса System.DirectoryServices.ActiveDirectoryRights.
    Написана для удобства перехвата исключений.

.PARAMETER  StrRight
    Строковое наименование элемента перечисления System.DirectoryServices.ActiveDirectoryRights.

.OUTPUTS
    System.DirectoryServices.ActiveDirectoryRights или $null. Возвращает объект типа System.DirectoryServices.ActiveDirectoryRights,
    соотвтетствующий заданному имени, или $null (если такой объект не может быть создан)
#>
Function Convert-ToAccessRight([STRING]$StrRight)
{
    $Res = $null
    $ErrorActionPreference = "SilentlyContinue"
    $Res = [System.DirectoryServices.ActiveDirectoryRights]::$StrRight
    $ErrorActionPreference = "Stop"
    Return $Res
}

<#
.SYNOPSIS
    Создает объект - право доступа AD по его строковому имени.

.Description
    Создает объект типа System.DirectoryServices.ActiveDirectoryRights. Принимает в качестве имени константы вида $SYSTEM_AD_GPO_PERMISSION_*
    и строковые наименования типов перечисления System.DirectoryServices.ActiveDirectoryRights

.PARAMETER  RightSTR
    Строковое имя создаваемого права доступа.

.OUTPUTS
    System.DirectoryServices.ActiveDirectoryRights или $null. Возвращает объект типа System.DirectoryServices.ActiveDirectoryRights, соответствующий
    переданному строковому описанию, или $null (если такой объект не удалось найти).
#>
Function Get-GPOAccessRightFromString([STRING]$RightSTR)
{


    Switch ($RightSTR)
    {
        $SYSTEM_AD_GPO_PERMISSION_READ
        {
            $Right = [System.DirectoryServices.ActiveDirectoryRights]::GenericRead
        }

        $SYSTEM_AD_GPO_PERMISSION_WRITE
        {
            $Right = [System.DirectoryServices.ActiveDirectoryRights]::GenericWrite
        }

        $SYSTEM_AD_GPO_PERMISSION_CREATE_ALL_CHILD_OBJECT
        {
            $Right = [System.DirectoryServices.ActiveDirectoryRights]::CreateChild
        }

        $SYSTEM_AD_GPO_PERMISSION_DELETE_ALL_CHILD_OBJECT
        {
            $Right = [System.DirectoryServices.ActiveDirectoryRights]::DeleteChild
        }

        $SYSTEM_AD_GPO_PERMISSION_FULL_CONTROL
        {
            $Right = [System.DirectoryServices.ActiveDirectoryRights]::GenericAll
        }

        default
        {
            $Right = $null
            $Right = Convert-ToAccessRight -StrRight $RightSTR
        }

    }

    Return $Right
}

<#
.SYNOPSIS
    Формирует объект, представляющий собой право доступа к объектам AD.

.Description
    Позволяет создать объект - правило доступа к объектам AD, зная тип доступа, строковое имя субъекта права и имя права.

.PARAMETER  Trustee
    Строковое имя пользователя (или группы), который является субъектом права создаваемого правила.

.PARAMETER  Act
    Тип доступа. Строковое наименования типов перечисления System.Security.AccessControl.AccessControlType (Allow или Deny)

.PARAMETER  Right
    Строковое наименования права доступа. Допустимо использовать константы вида $SYSTEM_AD_GPO_PERMISSION_*
    и строковые наименования типов перечисления System.DirectoryServices.ActiveDirectoryRights

.OUTPUTS
    System.DirectoryServices.ActiveDirectoryAccessRule или $null. Возвращает созданный объект правила доступа или $null (в случае, если
    создать объект правила не удалось).
#>
Function New-ADGPOAccessRule ([STRING]$Trustee,[STRING]$Act,[STRING]$Right)
{
    $DomainSID = Get-DomainSID

    #-----------------
    #Сначала разбираемся с субъектом прав.
    $objTrustee = $null
    #Смотрим, не является ли наш субъект стандартным. Если да, то можно получить его SID, а уже по нему - имя.
    #это обеспечит переносимость файлов конфигурации между разноязычными версиями ОС
    $TruteeSID = Get-WellKnownSIDFromName -Name $Trustee
    If ($TruteeSID -ne $null)
    {
        $objTrustee = New-Object -TypeName System.Security.Principal.SecurityIdentifier -ArgumentList $TruteeSID,$DomainSID
    }
    else #Субъект - не стандартный
    {
        [STRING]$FQDN = [System.DirectoryServices.ActiveDirectory.Domain]::GetCurrentDomain().Name
        $objTrustee = New-Object -TypeName System.Security.Principal.NTAccount -ArgumentList "$FQDN", "$Trustee"
    }
    If ($objTrustee -eq $null)
    {
        Write-Log -CurrentLogLevel 1 -Message "Не удалось найти участника безопасности, соответствующего имени $Trustee"
        Throw "Err_no_security_principal_found_for_trustee"
    }

    #-----------------
    #Теперь разбираемся с типом действия - разрешение это или запрет
    $objACT = [System.Security.AccessControl.AccessControlType]::$Act

    #-----------------
    #Формируем объект - задаваемое право
    If ($Right -eq $SYSTEM_AD_GPO_PERMISSION_APPLY) #Речь идет о праве на применение GPO, оно формируется иначе, чем остальные
    {
        $NewRule = New-Object System.DirectoryServices.ExtendedRightAccessRule  -ArgumentList $objTrustee, $Act
    }
    else
    {
        $objRihgt = Get-GPOAccessRightFromString -Right $Right
        if ($objRihgt -eq $null)
        {
            Write-Log -CurrentLogLevel 1 -Message "Не удалось определить право, соответствующее записи $Right"
            Throw "Err_cannot_determine_ad_rights"
        }
        $NewRule = New-Object -TypeName System.DirectoryServices.ActiveDirectoryAccessRule -ArgumentList $objTrustee, $objRihgt, $objACT
    }
    Return $NewRule
}


<#
.SYNOPSIS
    Сбрасывает разрешения (права доступа) для заданного объекта GPO и возвращает измененный объект.

.Description
    Функция используется для сброса разрешений (прав доступа) на объект GPO к значениям по умолчанию.
    Функция лишь возвращает объект и измененными правами доступа, не выполняя изменений в AD (она не делает Commit, его нужно
    вызывать на измененном объекте явным образом).

.PARAMETER  GPO
    Объект GPO, для которого нужно сбросить параметры доступа.

.PARAMETER ForceRemoveAllMode
    Переключатель режима полного удаления всех заданных разрешений. Если он задан - то будут удалены все правила доступа к
    объекту GPO. Если нет, то сначала будут удалены все правила доступа, а потом - заданы стандартные.

.OUTPUTS
    System.DirectoryServices.DirectoryEntry. Объект GPO, у которого сброшены права доступа.
#>
Function Reset-ADGPOPermissions([System.DirectoryServices.DirectoryEntry]$GPO, [SYSTEM.Management.Automation.SwitchParameter]$ForceRemoveAllMode=$false)
{
    #Удаляем правила доступа.
    $AccessRules = $GPO.ObjectSecurity.Access
    Foreach ($AccessRule in $AccessRules)
    {
        $GPO.ObjectSecurity.PurgeAccessRules($AccessRule.IdentityReference)
    }

    # В большинстве случаев нам не нужно удалять вообще все правила. Как минимум,
        # надо оставить доступ для Domain Controllers, Domain Admins и System

        if ($ForceRemoveAllMode -eq $false)
        {
            ##Задаем права для администраторов предприятия
            #--Чтение
            $NewRule = New-ADGPOAccessRule  -Trustee AccountEnterpriseAdminsSid -Act Allow -Right GenericRead
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #--Запись
            $NewRule = New-ADGPOAccessRule  -Trustee AccountEnterpriseAdminsSid -Act Allow -Right GenericWrite
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #--Создание дочерних элементов
            $NewRule = New-ADGPOAccessRule  -Trustee AccountEnterpriseAdminsSid -Act Allow -Right CreateChild
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #--Удаление дочерних элементов
            $NewRule = New-ADGPOAccessRule  -Trustee AccountEnterpriseAdminsSid -Act Allow -Right DeleteChild
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null


            ##Задаем права для контроллеров домена
            #--Чтение
            $NewRule = New-ADGPOAccessRule  -Trustee EnterpriseControllersSid -Act Allow -Right GenericRead
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null

            ##Задаем права для локальной системы
            #--Чтение
            $NewRule = New-ADGPOAccessRule  -Trustee LocalSystemSid -Act Allow -Right GenericRead
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #--Запись
            $NewRule = New-ADGPOAccessRule  -Trustee LocalSystemSid -Act Allow -Right GenericWrite
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #--Создание дочерних элементов
            $NewRule = New-ADGPOAccessRule  -Trustee LocalSystemSid -Act Allow -Right CreateChild
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #--Удаление дочерних элементов
            $NewRule = New-ADGPOAccessRule  -Trustee LocalSystemSid -Act Allow -Right DeleteChild
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null

            <##Задаем права для прошедших проверку
            #--Чтение
            $NewRule = New-ADGPOAccessRule  -Trustee AuthenticatedUserSid -Act Allow -Right GenericRead
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #--Применение
            $NewRule = New-ADGPOAccessRule  -Trustee AuthenticatedUserSid -Act Allow -Right $SYSTEM_AD_GPO_PERMISSION_APPLY
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null
            #>

            ##Задаем права для себя, чтобы иметь возможность сохранить GPO-шку
            $UserName = ([Security.Principal.WindowsIdentity]::GetCurrent()).Name
            $objTrustee = New-Object -TypeName System.Security.Principal.NTAccount -ArgumentList "$UserName"
            #--Запись
            $Right = [System.DirectoryServices.ActiveDirectoryRights]::GenericWrite
            $Act = [System.Security.AccessControl.AccessControlType]::Allow
            $NewRule = New-Object -TypeName System.DirectoryServices.ActiveDirectoryAccessRule -ArgumentList $objTrustee, $Right, $Act
            $GPO.ObjectSecurity.AddAccessRule($NewRule) | Out-Null

        }

    Return $GPO
}

#===============</Модуль ActiveDirectory: функции>=================