модуль microsoft.ad.object — управление объектами Active Directory

Примечание

Этот модуль входит в коллекцию microsoft.ad (версия 1.10.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install microsoft.ad. Для работы с этим модулем могут потребоваться дополнительные компоненты. Подробнее см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: microsoft.ad.object.

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Управляет объектами Active Directory и их атрибутами.

Требования

Следующие требования должны быть выполнены на хосте, который запускает этот модуль.

ActiveDirectory модуль PowerShell

Параметры

Параметр	Комментарии
attributes dictionary	Атрибуты, которые нужно добавить к объекту AD, удалить из него или задать для него. Значение каждого параметра атрибута должно быть словарём, где ключ — это атрибут LDAP, например `firstName`, `comment`, а значение — значение или список значений, задаваемых для этого атрибута. Значением атрибута может быть исходное строковое, целочисленное значение или значение bool, которое нужно добавить, удалить или задать для соответствующего атрибута. Значением также может быть словарь с ключом type, которому задано значение `bytes`, `date_time`, `security_descriptor` или `raw`, и значением этой записи под ключом value. Для типа `bytes` в качестве значения используется строка в кодировке base64, содержащая исходные байты для установки. Для типа `date_time` в качестве значения используется строка даты и времени в формате ISO 8601. Дата и время будут заданы как целочисленное значение Microsoft FILETIME — количество интервалов по 100 наносекунд с 1601-01-01 в UTC. Для типа `security_descriptor` в качестве значения используется строка Security Descriptor SDDL для атрибута `nTSecurityDescriptor`. Для типа `raw` задаётся значение типа int, string или boolean. Строковые значения атрибутов сравниваются с учётом регистра в управляемом объекте AD. Дополнительные сведения см. в разделе Справка по атрибутам LDAP. По умолчанию: `{}`
add dictionary	Словарь всех атрибутов и их значений, которые нужно добавить к управляемому объекту AD, если они ещё не заданы. Используется для атрибутов, которые могут содержать несколько значений. Если атрибут допускает только одно значение, используйте вместо этого set. По умолчанию: `{}`
remove dictionary	Словарь всех атрибутов и их значений, которые нужно удалить из управляемого объекта AD, если они заданы. Используется для атрибутов, которые могут содержать несколько значений. Если атрибут допускает только одно значение, используйте вместо этого set. По умолчанию: `{}`
set dictionary	Словарь всех атрибутов и их значений, которые нужно задать для управляемого объекта AD. Все существующие значения, отличающиеся от указанных, будут заменены. Порядок значений атрибута не проверяется; проверяется только то, что на объекте заданы исключительно запрошенные значения. Задайте значение null или пустой список, чтобы очистить все значения атрибута. По умолчанию: `{}`
description string	Описание объекта AD, которое нужно задать. Это значение задаётся для атрибута LDAP `description`.
display_name string	Отображаемое имя объекта AD, которое нужно задать. Это значение атрибута LDAP `displayName`.
domain_credentials list / elements=dictionary	Указывает учётные данные, которые следует использовать при работе с сервером, указанным в параметре name. Чтобы указать учётные данные для сервера домена по умолчанию, используйте запись без ключа name или параметры domain_username и domain_password. Этот параметр можно задать в значениях модуля по умолчанию для плейбука в группе `group/microsoft.ad.domain`. Дополнительные сведения см. в разделе Аутентификация AD в модулях. По умолчанию: `[]`
name string	Имя сервера, для которого предназначены эти учётные данные. Это значение должно соответствовать значениям, используемым в других параметрах, указывающих пользовательский сервер, например в параметре, который ссылается на учётную запись AD на другом сервере AD. Этот ключ можно опустить в одной из записей, чтобы указать учётные данные по умолчанию для случаев, когда сервер не задан, вместо использования domain_username и domain_password.
password string / обязательный	Пароль для подключения к серверу, указанному в параметре name.
username string / обязательный	Имя пользователя для подключения к серверу, указанному в параметре name.
domain_password string	Пароль для domain_username. Для указания учётных данных для аутентификации в домене по умолчанию также можно использовать вложенную запись domain_credentials без ключа name. Этот параметр можно задать в значениях модуля по умолчанию для плейбука в группе `group/microsoft.ad.domain`.
domain_server string	Указывает экземпляр служб домена Active Directory, к которому нужно подключиться. Можно указать полное доменное имя (FQDN) или имя NetBIOS. Если значение не задано, используется домен по умолчанию компьютера, на котором запущен PowerShell. Пользовательские учётные данные можно указать во вложенной записи domain_credentials без ключа name или с помощью параметров domain_username и domain_password. Этот параметр можно задать в значениях модуля по умолчанию для плейбука в группе `group/microsoft.ad.domain`.
domain_username string	Имя пользователя, которое следует использовать при работе с AD. Если значение не задано, для аутентификации будет использоваться пользователь подключения. Ansible не сможет использовать пользователя подключения, если для аутентификации не применяется Kerberos с делегированием учётных данных или CredSSP и для задачи не используется become. Для указания учётных данных для аутентификации в домене по умолчанию также можно использовать вложенную запись domain_credentials без ключа name. Этот параметр можно задать в значениях модуля по умолчанию для плейбука в группе `group/microsoft.ad.domain`.
identity string	Идентификатор объекта AD, используемый для поиска объекта, которым нужно управлять. Этот параметр необходимо задать, если не задан name, если объект переименовывается с помощью нового значения name или если объект перемещается в другой path. Идентификатором может быть GUID, представляющий значение `objectGUID`, `userPrincipalName`, `sAMAccountName`, `objectSid` или `distinguishedName`. Если параметр не задан, объект AD для управления выбирается по `distinguishedName` в формате `CN={{ name }},{{ path }}`. Если параметр path не задан, вместо него используется `defaultNamingContext`. При использовании модуля microsoft.ad.computer к концу `sAMAccountName` автоматически добавляется `$`, если указанные данные не совпали с объектом и уже не содержали `$` в конце.
name string	Значение `name` объекта AD, которым нужно управлять. Это не `sAMAccountName` объекта, а запись LDAP `cn` или `name` объекта в указанном пути. Используйте identity, чтобы выбрать объект для управления по его `sAMAccountName`. Если задан identity, а имя найденного по этому идентификатору объекта не совпадает с этим значением, объект будет переименован. Этот параметр необходимо задать, если не задан identity.
path string	Путь к OU или контейнеру, в котором должен находиться новый объект. При создании нового объекта он будет создан по указанному пути. Если путь не указан, для большинства типов объектов в качестве пути будет использоваться `defaultNamingContext` домена. Если управление выполняется найденным по identity существующим объектом, объект будет перемещён по пути, указанному этим параметром. Если путь не задан, объект не перемещается. У модулей microsoft.ad.computer, microsoft.ad.user и microsoft.ad.group есть собственные пути по умолчанию, настроенные на контроллере домена Active Directory. Можно задать буквальное значение `microsoft.ad.default_path`, которое соответствует значению по умолчанию, используемому при создании нового объекта.
protect_from_deletion boolean	Защищает объект от случайного удаления. Для объекта задаётся запрет на удаление. Прежде чем удалить объект через графический интерфейс или любой другой инструмент, не связанный с Ansible, необходимо снять защиту. Значение state=absent всё равно приведёт к удалению объекта AD, даже если он защищён от удаления. Допустимые значения: `false` `true`
state string	Задайте значение `present`, чтобы обеспечить наличие объекта AD. Задайте значение `absent`, чтобы удалить объект AD, если он существует. Если state=present, необходимо задать параметр name. Значение `absent` приводит к рекурсивному удалению объекта AD и всех дочерних объектов, если он является контейнером. Объект AD будет удалён, даже если он защищён от случайного удаления. Допустимые значения: `"absent"` `"present"` ← (по умолчанию)
type string	Тип объекта AD. Соответствует значению `objectClass` объекта AD. Примеры типов: `user`, `computer`, `group`, `subnet`, `contact`, `container`. Этот параметр обязателен, если state=present.

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: полная	Модуль может работать в режиме check_mode и возвращать прогноз изменения состояния, не изменяя целевой объект. Если режим не поддерживается, действие будет пропущено.
diff_mode	Поддержка: полная	В режиме diff будут возвращены сведения об изменениях (или о возможных изменениях в режиме check_mode).
platform	Платформа: windows	Целевые ОС и семейства ОС, с которыми можно работать.

Примечания

Примечание

Это универсальный модуль для создания объектов любого типа в Active Directory и управления ими. При создании объекта он не проверяет, заданы ли все необходимые значения по умолчанию для каждого типа. Если для управления этим типом объектов AD доступен специализированный модуль, рекомендуется использовать его.
Этот модуль необходимо запускать на целевом хосте Windows с установленным модулем ActiveDirectory.
Некоторые атрибуты LDAP могут иметь только одно значение, другие — несколько. Некоторые атрибуты доступны только для чтения и не могут быть изменены. Рекомендуется просмотреть метаданные схемы атрибута: System-Only — это значения только для чтения, а Is-Single-Value — атрибуты, допускающие только одно значение.
Попытка задать несколько значений для атрибута Is-Single-Value приводит к неопределённому поведению.
Если модуль запускается на сервере, который не является контроллером домена, необходимо использовать делегирование учётных данных через CredSSP или Kerberos с делегированием либо задать параметры domain_username и domain_password.

См. также

microsoft.ad.domain: Обеспечивает наличие домена Windows.
microsoft.ad.domain_controller: Управляет состоянием контроллера домена или рядового сервера Windows.
microsoft.ad.object_info: Собирает сведения об объекте Active Directory.
microsoft.ad.user: Управляет пользователями Active Directory.
microsoft.ad.computer: Управляет объектами компьютеров Active Directory.
microsoft.ad.group: Управляет объектами групп Active Directory.

Примеры

# Use this to get all valid types in a domain environment
# (Get-ADObject -SearchBase (Get-ADRootDSE).subschemaSubentry -Filter * -Properties objectClasses).objectClasses |
#     Select-String -Pattern "Name\s+'(\w+)'" |
#     ForEach-Object { $_.Matches.Groups[1].Value } |
#     Sort-Object

- name: Create a contact object
  microsoft.ad.object:
    name: MyContact
    description: My Contact Description
    type: contact
    state: present

- name: Rename a contact object
  microsoft.ad.object:
    identity: '{{ contact_obj.object_guid }}'
    name: RenamedContact
    type: contact
    state: present

- name: Move a contact object
  microsoft.ad.object:
    identity: '{{ contact_object.object_guid }}'
    name: MyContact
    path: OU=Contacts,DC=domain,DC=test
    type: contact
    state: present

- name: Remove a contact object in default path
  microsoft.ad.object:
    name: MyContact
    state: absent

- name: Remove a contact object in custom path
  microsoft.ad.object:
    name: MyContact
    path: OU=Contacts,DC=domain,DC=test
    state: absent

- name: Remove a contact by identity
  microsoft.ad.object:
    identity: '{{ contact_obj.object_guid }}'
    state: absent

- name: Create container object with custom attributes
  microsoft.ad.object:
    name: App
    attributes:
      set:
        wWWHomePage: https://ansible.com
    type: container
    state: present

- name: Clear attribute of any value
  microsoft.ad.object:
    name: App
    attributes:
      set:
        wWWHomePage: ~
    type: container
    state: present

- name: Edit object security with Everyone Allow All access
  microsoft.ad.object:
    name: App
    attributes:
      add:
        nTSecurityDescriptor:
          type: security_descriptor
          value: O:DAG:DAD:PAI(A;CI;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;WD)
    type: container
    state: present

- name: Ensure multiple values are present in attribute
  microsoft.ad.object:
    name: App
    attributes:
      add:
        extensionName:
          - value 1
          - value 2
    type: container
    state: present

- name: Ensure multiple values are not present in attribute
  microsoft.ad.object:
    name: App
    attributes:
      remove:
        extensionName:
          - value 1
          - value 3
    type: container
    state: present

Возвращаемые значения

Общие возвращаемые значения описаны здесь. Ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
distinguished_name string	Значение `distinguishedName` объекта AD, который был создан, удалён или изменён. Возвращается: всегда Пример: `"CN=TestUser,CN=Users,DC=domain,DC=test"`
object_guid string	Значение `objectGUID` объекта AD, который был создан, удалён или изменён. Если в режиме check mode был создан новый объект, будет возвращён GUID, состоящий из нулей. Возвращается: всегда Пример: `"d84a141f-2b99-4f08-9da0-ed2d26864ba1"`

Авторы

Jordan Borean (@jborean93)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/microsoft/ad/object_module.html