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

Примечание

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

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

Чтобы установить её, используйте: ansible-galaxy collection install microsoft.ad. Для использования этого модуля необходимы дополнительные требования, см. Требования для получения подробной информации.

Для использования в книге задач укажите: microsoft.ad.object.

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

Обзор

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

Требования

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

ActiveDirectory модуль PowerShell

END_OF_DOCUMENT_MARKER

Параметры

Параметр	Комментарии
attributes словарь	Атрибуты, которые нужно добавить, удалить или установить для объекта AD. Значение каждого атрибута должно быть словарем, где ключ — атрибут LDAP, например `firstName`, `comment`, а значение — значение или список значений для установки этого атрибута. Значение атрибута(ов) может быть строкой, целым числом или булевым значением для добавления, удаления или установки атрибута. Значение также может быть словарем со значением ключа type, установленным в `bytes`, `date_time`, `security_descriptor`, или `raw`, а значением для этого элемента в ключа value. Тип `bytes` имеет значение — строку, закодированную в base64, содержащую исходные байты, которые нужно установить. Тип `date_time` имеет значение — строку в формате ISO 8601 DateTime, представляющую дату и время, которые нужно установить. Дата и время будут установлены как целое значение Microsoft FILETIME, которое представляет количество 100 наносекунд, прошедших с 1601-01-01 по UTC. Тип `security_descriptor` имеет значение — строку SDDL дескриптора безопасности, используемую для атрибута `nTSecurityDescriptor`. Тип `raw` — это целое число, строка или булево значение для установки. Значения строковых атрибутов сравниваются с использованием чувствительного к регистру сопоставления с объектом AD, который управляется. Для получения дополнительной информации см. справочник по атрибутам LDAP. По умолчанию: `{}`
add словарь	Словарь всех атрибутов и их значений, которые нужно добавить к управляемому объекту AD, если они еще не присутствуют. Используется для атрибутов, которые могут содержать несколько значений. Если атрибут допускает только одно значение, используйте set. По умолчанию: `{}`
remove словарь	Словарь всех атрибутов и их значений, которые нужно удалить из управляемого объекта AD, если они присутствуют. Используется для атрибутов, которые могут содержать несколько значений. Если атрибут допускает только одно значение, используйте set. По умолчанию: `{}`
set словарь	Словарь всех атрибутов и их значений, которые нужно установить для управляемого объекта AD. Это заменит любые существующие значения, если они не совпадают с запрошенными. Порядок значений атрибутов не проверяется, проверяется только то, что запрошенные значения являются единственными значениями в атрибуте объекта. Установите это в null или пустой список, чтобы очистить любые значения для атрибута. По умолчанию: `{}`
description строка	Описание объекта AD для установки. Это значение, устанавливаемое для атрибута LDAP `description`.
display_name строка	Отображаемое имя объекта AD для установки. Это значение атрибута LDAP `displayName`.
domain_credentials список / элементы=словарь	Указывает учетные данные, которые нужно использовать при использовании сервера, указанного в name. Для указания учетных данных для сервера домена по умолчанию используйте запись без ключа name или используйте параметры domain_username и domain_password. Это можно установить в параметрах модуля в сценарии в группе `group/microsoft.ad.domain`. Для получения дополнительной информации см. аутентификацию в модулях AD. По умолчанию: `[]`
name строка	Имя сервера, для которого предназначены эти учетные данные. Это значение должно соответствовать значению, используемому в других параметрах, которые задают настраиваемый сервер, например, параметру, который ссылается на идентификатор AD, расположенный на другом сервере AD. Этот ключ можно опустить в одной записи, чтобы указать учетные данные по умолчанию для использования, когда сервер не указан, вместо использования domain_username и domain_password.
password строка / обязательно	Пароль для подключения к серверу, указанному в name.
username строка / обязательно	Имя пользователя для подключения к серверу, указанному в name.
domain_password строка	Пароль для domain_username. Подзапись domain_credentials без ключа name также может использоваться для указания учетных данных для проверки подлинности по умолчанию для домена. Это можно установить в параметрах модуля в сценарии в группе `group/microsoft.ad.domain`.
domain_server строка	Указывает экземпляр Active Directory Domain Services для подключения. Может быть в формате FQDN или NetBIOS имени. Если не указано, значение основано на домене по умолчанию компьютера, на котором выполняется PowerShell. Настраиваемые учетные данные можно указать в записи domain_credentials без ключа name или через domain_username и domain_password. Это можно установить в параметрах модуля в сценарии в группе `group/microsoft.ad.domain`.
domain_username строка	Имя пользователя, используемое при взаимодействии с AD. Если это не задано, пользователь, используемый для аутентификации, будет пользователем подключения. Ansible не сможет использовать пользователя подключения, если аутентификация не Kerberos с делегированием учетных данных или CredSSP, или используется become в задаче. Подзапись domain_credentials без ключа name также может использоваться для указания учетных данных для проверки подлинности по умолчанию для домена. Это можно установить в параметрах модуля в сценарии в группе `group/microsoft.ad.domain`.

identity string	Идентификатор объекта Active Directory, используемый для поиска объекта Active Directory для управления. Это необходимо указать, если параметр name не задан, при попытке переименовать объект с новым name или при попытке перемещения объекта в другой path. Идентификатор может быть представлен в виде GUID, представляющего значение `objectGUID`, `userPrincipalName`, `sAMAccountName`, `objectSid`, или `distinguishedName`. Если параметр опущен, объект Active Directory для управления выбирается по `distinguishedName` с использованием формата `CN={{ name }},{{ path }}`. Если параметр path не определен, используется `defaultNamingContext` вместо него. При использовании модуля microsoft.ad.computer идентификатор будет автоматически добавлять `$` в конец `sAMAccountName`, если предоставленное значение не привело к совпадению и не содержало `$` в конце.
name string	Имя объекта Active Directory для управления. Это не полное имя объекта, а запись 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 все равно удалит объект Active Directory, даже если он помечен как защищенный от случайного удаления. Варианты: `false` `true`
state string	Установите в значение `present`, чтобы гарантировать существование объекта Active Directory. Установите в значение `absent`, чтобы удалить объект Active Directory, если он существует. Параметр name должен быть задан, когда state=present. Использование `absent` рекурсивно удалит объект Active Directory и все дочерние объекты, если это контейнер. Он также удалит объект Active Directory, даже если объект помечен как защищенный от случайного удаления. Варианты: `"absent"` `"present"` ← (по умолчанию)
type string	Тип объекта Active Directory. Это соответствует типу объекта Active Directory. Примеры типов: `user`, `computer`, `group`, `subnet`, `contact`, `container`. Требуется при state=present.

Атрибуты

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

Примечания

Примечание

Этот модуль является универсальным модулем, используемым для создания и управления любым типом объектов в Active Directory. Он не будет проверять, установлены ли все правильные значения по умолчанию для каждого типа при создании. Если доступен модуль для конкретного типа объекта Active Directory, рекомендуется использовать его.
Этот модуль должен выполняться на целевом хосте 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 строка	Уникальное `distinguishedName` объекта AD, который был создан, удалён или изменён. Возвращается: всегда Пример: `"CN=TestUser,CN=Users,DC=domain,DC=test"`
object_guid строка	Уникальный `objectGUID` объекта AD, который был создан, удалён или изменён. Если новый объект был создан в режиме проверки, будет возвращён GUID из нулей. Возвращается: всегда Пример: `"d84a141f-2b99-4f08-9da0-ed2d26864ba1"`

Авторы

Jordan Borean (@jborean93)

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

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