Синтаксис и общие параметры командлетов PowerShell

Для управления доменом «Эллес» через elles-ws используются поддерживаемые командлеты PowerShell модуля ActiveDirectory.

Все операции, описанные в этом разделе, выполняются через сервер ADWS elles-ws. Для явного выбора сервера в командах указывайте параметр -Server.

Общий формат

Общий формат команды:

<Cmdlet> [parameters] -Server <DC_FQDN>:9389 -Credential <Credential>

Описание элементов:

  • <Cmdlet> — имя командлета (например, Get-ADUser, Set-ADAccountPassword, Get-ADDomainController);

  • [parameters] — обязательные и необязательные параметры команды, включая фильтры, имена объектов, значения атрибутов;

    Имя параметра начинается с символа -. Значение параметра указывается после его имени через пробел. Некоторые параметры являются переключателями и не требуют значения. Конкретный набор обязательных и необязательных параметров зависит от командлета и выбранного набора параметров.

  • -Server — полное доменное имя (FQDN) хоста, на котором развернут сервер ADWS elles-ws;

  • -Credential — учетные данные для аутентификации.

    Это может быть, например, объект PSCredential, созданный через Get-Credential или New-Object PSCredential. Поддерживает Kerberos-аутентификацию через UPN (<user>@<REALM>) или доменное имя (DOMAIN\username).

Например:

Get-ADUser -Identity testuser -Server dc01.example.com:9389 -Credential (Get-Credential)

Подробнее: Microsoft Learn: about_Parameters.

Аутентификация

elles-ws использует Kerberos-аутентификацию.

Параметр -Credential

Параметр -Credential задает учетную запись, от имени которой выполняется операция.

Если параметр не указан, по умолчанию используются учетные данные текущего пользователя Windows.

Для интерактивного ввода учетных данных:

$cred = Get-Credential

Get-ADUser -Identity ivanov `
    -Server dc01.example.com `
    -Credential $cred

Пример аутентификации с явным указанием учетных данных:

# Создание объекта учетных данных
$sec = ConvertTo-SecureString 'changeme' -AsPlainText -Force
$cred = New-Object PSCredential('EXAMPLE\Administrator', $sec)

# Использование в командлетах
Get-ADRootDSE -Server dc01.example.com:9389 -Credential $cred
Get-ADDomain -Server dc01.example.com:9389 -Credential $cred
Get-ADUser -Server dc01.example.com:9389 -Credential $cred -Identity Administrator

Если клиент находится в домене и пользователь вошел в систему с доменной учетной записью, можно опустить -Credential:

Get-ADRootDSE -Server dc01.example.com:9389
Get-ADDomain -Server dc01.example.com:9389

При использовании текущего контекста убедитесь, что:

  • клиент имеет действительный билет Kerberos (проверьте через klist);

  • DNS-запись SRV _adws._tcp.example.com указывает на сервер elles-ws;

  • время на клиенте и сервере синхронизировано (разница < 5 минут).

Пользователь должен обладать правами, необходимыми для выполняемой операции.

В примерах в разделе предполагается, что PowerShell запущен от имени доменной учетной записи с необходимыми правами. Параметр -Credential явно не указывается.

Подробнее: Microsoft Learn: Add Credential support to PowerShell functions.

Параметр -Authtype

Командлеты модуля ActiveDirectory поддерживают параметр -AuthType со значениями Negotiate и Basic; значением по умолчанию является Negotiate. При работе с elles-ws соединение должно быть аутентифицировано Kerberos, поэтому Basic не используется.

Как правило, параметр -AuthType указывать не требуется:

Get-ADUser -Identity testuser -Server dc01.example.com:9389

При необходимости его можно указать явно:

Get-ADUser -Identity testuser `
    -Server dc01.example.com:9389 `
    -AuthType Negotiate
Negotiate является режимом клиента PowerShell, а не отдельным механизмом Kerberos. Сервер elles-ws принимает только Kerberos-аутентификацию, поэтому у пользователя должен быть действительный Kerberos-контекст для указанного FQDN сервера.

Подробнее см. описание параметра -AuthType в справке соответствующего командлета PowerShell.

Выбор сервера

Параметр -Server определяет сервер, через который выполняется операция.

Чтобы запрос выполнялся именно через elles-ws, его следует указывать явно:

Get-ADDomain -Server dc01.example.com:9389

Microsoft допускает указание сервера в формате hostname:port. В примерах в разделе используется FQDN, поскольку соединение аутентифицируется Kerberos.

Подробнее см. описание параметра -Server в справке соответствующего командлета PowerShell.

Указание объекта

Для операций над конкретным объектом обычно используется параметр -Identity.

Например:

Get-ADUser -Identity testuser -Server dc01.example.com:9389

Для разных типов объектов допустимые идентификаторы могут различаться. Обычно можно использовать DN, GUID, SID или идентификатор объекта, например sAMAccountName.

При поиске нескольких объектов вместо -Identity обычно используется -Filter:

Get-ADUser -Filter * -Server dc01.example.com:9389

Для ограничения поиска определенной частью каталога могут использоваться -SearchBase и -SearchScope, если они поддерживаются конкретным командлетом.

Подробнее:

Получение дополнительных свойств

Командлеты получения объектов возвращают стандартный набор свойств. Дополнительные свойства указываются параметром -Properties.

Например, получение времени последней смены пароля:

Get-ADUser -Identity testuser `
    -Properties PasswordLastSet `
    -Server dc01.example.com:9389

Для получения всех доступных свойств:

Get-ADUser -Identity testuser `
    -Properties * `
    -Server dc01.example.com:9389

Подробнее см. описание параметра -Properties в справке соответствующего командлета PowerShell.

Общие параметры PowerShell

Поддерживаемые командлеты также принимают стандартные общие параметры PowerShell, например:

  • -Verbose — вывод дополнительных сведений;

  • -Debug — вывод отладочных сообщений;

  • -ErrorAction — способ обработки ошибок;

  • -ErrorVariable — сохранение ошибки в переменной.

Пример использования:

Get-ADUser -Identity testuser `
    -Server dc01.example.com:9389 `
    -ErrorAction Stop

Подробнее: Microsoft Learn: about_CommonParameters.

Ограничение области поиска

Командлеты поиска могут поддерживать параметры:

  • -SearchBase — DN объекта, с которого начинается поиск;

  • -SearchScope — область поиска;

  • -ResultSetSize — максимальное количество возвращаемых объектов;

  • -ResultPageSize — размер страницы результатов.

Пример использования:

Get-ADUser -Filter * `
    -SearchBase "OU=Users,DC=example,DC=com" `
    -Server dc01.example.com

Допустимые параметры конкретного командлета следует проверять в его справке.

Передача объектов по конвейеру

PowerShell позволяет передавать результат одного командлета следующему через оператор |.

Например, получение пользователей и экспорт результата в CSV:

Get-ADUser -Filter * -Properties PasswordLastSet |
    Export-Csv -Path users.csv -NoTypeInformation

В этом примере запрос Get-ADUser выполняется через ADWS, а Export-Csv обрабатывает полученные данные локально на клиенте Windows.

Аналогично можно использовать результаты клиентских командлетов для массового выполнения поддерживаемых операций:

Import-Csv .\users.csv | ForEach-Object {
    Set-ADUser -Identity $_.SamAccountName -Description $_.Description
}

Import-Csv и ForEach-Object выполняются локально, а каждый вызов Set-ADUser представляет отдельную операцию с объектом каталога.

Просмотр синтаксиса командлета

Для получения актуального синтаксиса установленного модуля используйте:

Get-Command Get-ADUser -Syntax

Для просмотра всех параметров:

Get-Help Get-ADUser -Parameter *

Список командлетов установленного модуля ActiveDirectory:

Get-Command -Module ActiveDirectory
Наличие командлета в модуле ActiveDirectory не означает, что он поддерживается elles-ws. Используйте только командлеты, указанные как поддерживаемые в документации elles-ws.

Обновлено: