Руководство по атрибутам

Атрибуты LDAP

Одним из ключевых компонентов Active Directory от Microsoft (AD) является база данных протокола облегченного доступа к каталогам (LDAP). Эта база данных содержит всю информацию, относящуюся к среде AD, например сведения о пользователях, компьютерах, подразделениях и многое другое. Каждый объект содержит динамический набор атрибутов, описывающих объект и соответствующих схеме. Например, у пользователей есть такие атрибуты, как firstName, country, sAMAccountName, описывающие сам объект. В документации Microsoft перечислены все встроенные атрибуты AD в схеме атрибутов AD. Например, атрибут SAM-Account-Name содержит метаданные этого атрибута, в том числе такие поля:

• Ldap-Display-Name — отображаемое имя LDAP
• Syntax — базовый тип значения, хранящегося в атрибуте
• System-Only — задается ли атрибут системой, что фактически делает его доступным только для чтения
• Is-Single-Value — является ли значение атрибута одиночным или представляет собой массив/список значений

Ldap-Display-Name — это имя/ключ атрибута, на который ссылается модуль Ansible. Например, для управления атрибутом SAM-Account-Name используется ключ sAMAccountName. С каждым атрибутом связано как минимум одно значение, но некоторые атрибуты могут иметь несколько значений. Например, sAMAccountName — это атрибут Is-Single-Value, поэтому у него только одно значение, а userCert может содержать несколько значений. Оснастку Active Directory Users and Computers (или dsa.msc) можно использовать для просмотра этих атрибутов LDAP в расширенном режиме. Это позволяет просматривать существующие значения, а также атрибуты, которые можно задавать для объекта.

Схему LDAP в AD также можно расширить, добавив пользовательские атрибуты организации. Эти пользовательские атрибуты также поддерживаются модулями этой коллекции. Чтобы получить сведения о схеме LDAP для атрибутов, выполните в PowerShell следующую команду:

Function Get-AttributeMetadata {
    [CmdletBinding()]
    param ([Parameter(ValueFromPipeline)][string[]]$Name)

    begin {
        $schema = (Get-ADRootDSE -Properties subschemaSubentry).subschemaSubentry
        $getParams = @{
            SearchBase = $schema
            LDAPFilter = '(objectClass=*)'
            Properties = 'attributeTypes'
        }
        $attributes = (Get-ADObject @getParams).attributeTypes
        $queried = $false
    }

    process {
        foreach ($n in $Name) {
            $queried = $true
            $attributes | Where-Object {
                $_ -like "*Name '$n'*"
            }
        }
    }

    end {
        if (-not $queried) {
            $attributes
        }
    }
}

# Display all attributes
Get-AttributeMetadata

# Get specific attributes
Get-AttributeMetadata -Name sAMAccountName, o, objectGuid

Вывод имеет следующий формат:

( $ATTRIBUTE_OID NAME '$ATTRIBUTE_NAME' SYNTAX '$TYPE_OID' [SINGLE-VALUE|NO-USER-MODIFICATION] )

Параметр $TYPE_OID указывает тип значения, которое можно использовать для этого атрибута. Найдите OID в Интернете, чтобы получить дополнительную информацию. Параметр SINGLE-VALUE указывает, может ли атрибут хранить только одно значение. Параметр NO-USER-MODIFICATION указывает, доступен ли атрибут только для чтения и нельзя ли его задать.

В последнем примере выводятся следующие данные:

( 1.2.840.113556.1.4.221 NAME 'sAMAccountName' SYNTAX '1.3.6.1.4.1.1466.115.121.1.15' SINGLE-VALUE )
( 2.5.4.10 NAME 'o' SYNTAX '1.3.6.1.4.1.1466.115.121.1.15' )
( 1.2.840.113556.1.4.2 NAME 'objectGUID' SYNTAX '1.3.6.1.4.1.1466.115.121.1.40' SINGLE-VALUE NO-USER-MODIFICATION )

Это показывает, что sAMAccountName — строка, которая может иметь только одно значение. Атрибут o тоже является строкой, но может хранить несколько значений. objectGUID — это значение типа «массив байтов», которое может иметь только одно значение и доступно только для чтения.

Задание атрибутов

В каждом модуле, который управляет объектом Active Directory, есть параметр attributes для непосредственной настройки атрибутов LDAP. Словарь принимает три ключа:

• add — добавляет значения атрибута, если их еще нет
• remove — удаляет значения атрибута, если они есть
• set — заменяет существующие значения атрибута указанными.

Каждому из этих ключей соответствует значение-словарь, в котором ключи — это имена атрибутов LDAP в формате ldapDisplayName, а значения — задаваемые значения. Поскольку атрибут LDAP может содержать несколько значений, указанное значение может быть одиночным или представлять собой список, например:

- microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      set:
        comment: My Comment
        extensionName:
        - Extension Value 1
        - Extension Value 2
        - Extension Value 3

Пример выше задаст атрибуту LDAP comment объекта MyUser указанное значение. Кроме того, он обеспечит, чтобы атрибут extensionName содержал именно эти три значения, удалив все остальные, если они есть.

Ключ add можно использовать, чтобы добавить указанные значения атрибута LDAP в список значений атрибута. Для атрибутов под ключом remove выполняется обратное: указанные значения будут удалены, если они присутствуют у соответствующего атрибута. Например:

- microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      add:
        extensionName:
        - Extension Value 1
        - Extension Value 3
      remove:
        extensionName:
        - Extension Value 2

Пример выше обеспечит, чтобы у extensionName были значения Extension Value 1, Extension Value 3, и удалит Extension Value 2, если оно задано. Поскольку ключ set не использовался, существующие значения не будут изменены, кроме тех, которые указаны в записи remove.

Чтобы очистить значение атрибута, укажите атрибут под ключом set и задайте значение null (~) или пустой список. Например:

- microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      set:
        # Null can either be represented by no value
        # or with tilde (~)
        comment: ~
        company:
        extensionName: []

Эта задача очистит значения атрибутов comment, company и extensionName.

Типы атрибутов

В атрибуте могут храниться значения нескольких типов. К распространенным типам относятся:

• Строки
• Целые числа
• Логические значения
• Массивы байтов
• Даты
• Дескрипторы безопасности

Задать строковое, целочисленное или логическое значение в задаче Ansible можно непосредственно с помощью синтаксиса YAML, например:

string: This is a string
integer: 1
boolean: true

Эти простые типы также можно представить в виде словаря с ключами type и value. Ключ типа можно задать одним из следующих значений:

• bool — значение преобразуется в логическое
• bytes — значение декодируется как строка base64
• date_time — значение декодируется как строка даты и времени в формате ISO 8601
• int — значение декодируется как целое число
• security_descriptor — значение декодируется как строка SDDL
• string — значение преобразуется в строку
• raw — значение используется как есть; это тип по умолчанию

Это выглядит следующим образом:

- microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      set:
        # comment: A raw value that is a string
        comment:
          type: raw
          value: A string

        # userAccountControl: 1234
        userAccountControl:
          type: int
          value: 1234

        # extensionName: ['Value 1', 'Value 2']
        extensionName:
        - type: raw
          value: Value 1
        - type: raw
          value: Value 2

Сложное значение-словарь со структурой type и value действительно требуется только для более сложных типов, перечисленных ниже. Если не указано иное, значение считается типом type: raw.

- microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      set:
        # Attribute with single value
        dsaSignature:
          type: bytes
          value: YmluYXJ5
        # Attribute with multiple values
        userCertificate:
        - type: bytes
          value: Zm9vYmFy
        - type: bytes
          value: YmFyZm9v

- vars:
    sig_data: "{{ lookup('ansible.builtin.file', '/path/to/my/sig') }}"
  microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      set:
        # Attribute with single value
        dsaSignature:
          type: bytes
          value: "{{ sig_data | ansible.builtin.b64encode }}"

- microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      set:
        dateAttributeSingleValue:
          type: date_time
          value: '2019-09-07T15:50:00+00:00'
        dateAttributeMultipleValue:
        - type: date_time
          value: '2019-09-07T15:50:00Z'
        - type: date_time
          value: '2019-09-07T11:50:00-04:00'

$dt = '2019-09-07T15:50:00Z'
$dtVal = [DateTimeOffset]::ParseExact(
    $dt,
    [string[]]@("yyyy-MM-dd'T'HH:mm:ss.FFFFFFFK"),
    [System.Globalization.CultureInfo]::InvariantCulture,
    [System.Globalization.DateTimeStyles]::AssumeUniversal)
$dtVal.UtcDateTime.ToFileTimeUtc()

- microsoft.ad.user:
    name: MyUser
    state: present
    attributes:
      set:
        nTSecurityDescriptor:
          type: security_descriptor
          value: O:DAG:DAD:PAI(A;CI;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;WD)

$dn = 'CN=ObjectName,DC=domain,DC=test'
$obj = Get-ADObject -Identity $dn -Properties nTSecurityDescriptor
$obj.nTSecurityDescriptor.GetSecurityDescriptorSddlForm('All')

Атрибуты поиска DN

Некоторые атрибуты Active Directory хранятся в виде значения различительного имени (DN), ссылающегося на другой объект AD. Некоторые модули позволяют искать DN по более понятному человеку значению, например managed_by. Значения этих параметров должны быть строкой или словарем с ключом name и необязательным ключом server. Строковое значение или значение name — это идентификатор для поиска, а server — сервер домена, на котором выполняется поиск идентификатора. Идентификатор для поиска можно указать как distinguishedName, objectGUID, objectSid, sAMAccountName или userPrincipalName. Ниже приведен пример поиска DN с помощью sAMAccountName — со строковым значением или в виде словаря:

- name: Find managed_by using string value
  microsoft.ad.group:
    name: My Group
    scope: global
    managed_by: Domain Admins

- name: Find managed_by using dictionary value with a server
  microsoft.ad.group:
    name: My Group
    scope: global
    managed_by:
      name: Domain Admins
      server: OtherDC

Некоторые параметры модулей также позволяют задавать список значений DN для атрибута. Для значений списка используются те же правила, что и для атрибутов с одиночным значением: каждый поиск DN задается строкой или словарем с ключом name и необязательным ключом server.

- name: Specify a list of DNs to set
  microsoft.ad.computer:
    identity: TheComputer
    delegates:
      set:
      - FileShare
      - name: ServerA
        server: OtherDC

Для атрибутов-списков с параметрами подчиненного ключа add/remove/set параметру lookup_failure_action также можно присвоить значение fail (по умолчанию), ignore или warn. Если для параметра fail какой-либо поиск завершится неудачно, задача завершится с ошибкой; значение ignore игнорирует недействительные результаты поиска, а значение warn выдает предупреждение, но продолжает выполнение при неудачном поиске.

- name: Specify a list of DNs to set - ignoring lookup failures
  microsoft.ad.computer:
    identity: TheComputer
    delegates:
      lookup_failure_action: ignore
      set:
      - FileShare
      - MissingUser

Если указан ключ server, поиск будет выполняться с использованием указанного значения сервера. Для этого сервера также можно задать учетные данные с помощью параметра domain_credentials.

- name: Set member with lookup on different server
  microsoft.ad.group:
    name: MyGroup
    state: present
    members:
      add:
      - GroupOnDefaultDC
      - name: GroupOnDefaultDC2
      - name: GroupOnOtherDC
        server: OtherDC
    domain_credentials:
    - username: UserForDefaultDC
      password: PasswordForDefaultDC
    - name: OtherDC
      username: UserForOtherDC
      password: PasswordForOtherDC

В приведенном выше примере поиск GroupOnOtherDC будет выполняться с помощью OtherDC под именем пользователя UserForOtherDC.

В документации параметра модуля будет указано, поддерживает ли он поиск или требуется явно указать значение DN.