модуль microsoft.ad.user — управление пользователями Active Directory

Примечание

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

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

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

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

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

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

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

Требования

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

ActiveDirectory модуль PowerShell

Параметры

Параметр	Комментарии
account_locked boolean	`no` разблокирует заблокированную учетную запись пользователя. Обратите внимание, что администратор не может заблокировать учетную запись. Учетные записи блокируются в результате действий пользователей; администратор может только разблокировать заблокированную учетную запись. Если необходимо отключить учетную запись административным способом, задайте для enabled значение `no`. Варианты: `false` `true`
attributes dictionary	Атрибуты, которые нужно добавить в объект AD, удалить из него или задать. Значение каждого параметра атрибута должно быть словарем, где ключ — атрибут LDAP, например `firstName`, `comment`, а значение — значение или список значений, которые нужно задать для этого атрибута. Значения атрибута могут быть необработанными строками, целыми числами или логическими значениями, которые нужно добавить, удалить или задать для соответствующего атрибута. Значением также может быть словарь с ключом type, которому присвоено значение `bytes`, `date_time`, `security_descriptor` или `raw`, и значением этой записи в ключе value. Тип `bytes` принимает в качестве значения строку в кодировке base64, содержащую необработанные байты для записи. Тип `date_time` принимает в качестве значения строку даты и времени в формате ISO 8601. Дата и время будут заданы как целочисленное значение Microsoft FILETIME — количество интервалов по 100 наносекунд с 1601-01-01 в формате UTC. Тип `security_descriptor` принимает в качестве значения строку SDDL дескриптора безопасности, используемую для атрибута `nTSecurityDescriptor`. Тип `raw` принимает целое число, строку или логическое значение. Строковые значения атрибутов сравниваются с учетом регистра в управляемом объекте AD. Дополнительные сведения см. в разделе Справка по атрибутам LDAP. По умолчанию: `{}`
add dictionary	Словарь всех атрибутов и их значений, которые нужно добавить в управляемый объект AD, если их там еще нет. Используется для атрибутов, которые могут содержать несколько значений. Если атрибут допускает только одно значение, используйте вместо этого set. По умолчанию: `{}`
remove dictionary	Словарь всех атрибутов и их значений, которые нужно удалить из управляемого объекта AD, если они там есть. Используется для атрибутов, которые могут содержать несколько значений. Если атрибут допускает только одно значение, используйте вместо этого set. По умолчанию: `{}`
set dictionary	Словарь всех атрибутов и их значений, которые нужно задать для управляемого объекта AD. Заменяет существующие значения, если они не совпадают с указанными. Порядок значений атрибутов не проверяется; проверяется только то, что указанные значения являются единственными значениями атрибута объекта. Укажите null или пустой список, чтобы очистить все значения атрибута. По умолчанию: `{}`
city string	Задает город пользователя. Это значение атрибута LDAP `l`.
company string	Задает название компании пользователя. Это значение атрибута LDAP `company`.
country string	Задает код страны пользователя. Обратите внимание, что это двухсимвольный код ISO 3166. Это значение атрибута LDAP `c`.
delegates псевдонимы: principals_allowed_to_delegate dictionary	Объекты субъектов, которым текущий объект AD может доверять делегирование; их можно добавить, удалить или задать. Значение каждого подчиненного ключа — список значений в формате строки `distinguishedName`, `objectGUID`, `objectSid`, `sAMAccountName` или `userPrincipalName` либо словарь с ключом name и необязательным ключом server. Это значение атрибута LDAP `msDS-AllowedToActOnBehalfOfOtherIdentity`. Это крайне важный с точки зрения безопасности атрибут, поскольку он позволяет указанным субъектам выдавать себя за любую учетную запись при аутентификации с использованием управляемого объекта компьютера AD. Чтобы удалить все субъекты, используйте set с пустым списком. Дополнительные сведения о поиске DN см. в разделе Атрибуты поиска DN. Дополнительные сведения о добавлении, удалении и задании параметров-списков см. в разделе Задание значений параметров-списков.
add list / элементы=any	Добавляет указанных субъектов в список субъектов, которым разрешено делегирование. Все существующие субъекты, не указанные в add, останутся без изменений, если они не указаны в remove или отсутствуют в set.
lookup_failure_action string	Определяет действие при сбое поиска DN. Значение `fail` приводит к сбою задачи. Значение `ignore` игнорирует значение и продолжает выполнение. Значение `warn` игнорирует значение, выводит предупреждение и продолжает выполнение. Варианты: `"fail"` ← (по умолчанию) `"ignore"` `"warn"`
remove list / элементы=any	Удаляет указанных субъектов из списка субъектов, которым разрешено делегирование. Все существующие субъекты, не указанные в remove, останутся без изменений, если задан параметр set.
set list / элементы=any	Задает список субъектов, которым разрешено делегирование. Все существующие субъекты, не указанные в этом списке, будут удалены. Укажите пустой список, чтобы удалить всех субъектов, которым разрешено делегирование.
description string	Описание, задаваемое для объекта AD. Это значение атрибута LDAP `description`.
display_name string	Отображаемое имя, задаваемое для объекта AD. Это значение атрибута LDAP `displayName`.
domain_credentials list / элементы=dictionary	Указывает учетные данные, которые следует использовать при подключении к серверу, указанному в name. Чтобы указать учетные данные для сервера домена по умолчанию, используйте запись без ключа name или параметры domain_username и domain_password. Эти параметры можно задать в разделе значений модуля по умолчанию для play, в группе `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. Этот параметр можно задать в разделе значений модуля по умолчанию для play, в группе `group/microsoft.ad.domain`.
domain_server string	Указывает экземпляр служб домена Active Directory для подключения. Можно указать полное доменное имя (FQDN) или имя NetBIOS. Если значение не указано, используется домен по умолчанию компьютера, на котором выполняется PowerShell. Пользовательские учетные данные можно указать в записи domain_credentials без ключа name либо с помощью параметров domain_username и domain_password. Этот параметр можно задать в разделе значений модуля по умолчанию для play, в группе `group/microsoft.ad.domain`.
domain_username string	Имя пользователя для взаимодействия с AD. Если значение не задано, для аутентификации будет использоваться пользователь подключения. Ansible не сможет использовать пользователя подключения, если для аутентификации не применяется Kerberos с делегированием учетных данных или CredSSP и для задачи не используется become. Для указания учетных данных аутентификации в домене по умолчанию также можно использовать запись domain_credentials без ключа name. Этот параметр можно задать в разделе значений модуля по умолчанию для play, в группе `group/microsoft.ad.domain`.
email string	Задает адрес электронной почты пользователя. Это запись в AD; она не настраивает серверы или системы электронной почты. Это значение атрибута LDAP `mail`.
enabled boolean	Значение `yes` включает учетную запись пользователя. Значение `no` отключает учетную запись. При создании новой учетной записи по умолчанию используется значение `yes`, если указан параметр password. Если password не указан, учетная запись пользователя не будет включена. Варианты: `false` `true`
firstname string	Задает имя пользователя. Это значение атрибута LDAP `givenName`.
groups dictionary	Указывает группы, в которые следует добавить пользователя, из которых его следует удалить или членство в которых следует задать. Чтобы удалить членство во всех группах, используйте set с пустым списком. Обратите внимание, что пользователей нельзя удалить из основной группы (например, «Пользователи домена»). При попытке сделать это будет выведено предупреждение. Добавление пользователя в группу и его удаление из группы выполняется для объекта группы AD. Если группа является объектом другого домена, для выполнения операции могут потребоваться явные значения server и domain_credentials. Каждому подчиненному ключу присваивается список объектов групп, в которые следует добавить пользователя, из которых его следует удалить или членство в которых следует задать соответственно. Группу можно указать в формате `distinguishedName`, `objectGUID`, `objectSid` или `sAMAccountName`. Значение каждого подчиненного ключа — список объектов групп в формате строки `distinguishedName`, `objectGUID`, `objectSid`, `sAMAccountName` или `userPrincipalName` либо словарь с ключом name и необязательным ключом server. Дополнительные сведения о поиске DN см. в разделе Атрибуты поиска DN. Дополнительные сведения о добавлении, удалении и задании параметров-списков см. в разделе Задание значений параметров-списков.
add list / элементы=any	Группы, в которые нужно добавить пользователя.
lookup_failure_action псевдонимы: missing_behaviour string	Определяет поведение, если группа, указанная в `groups`, не является допустимым именем группы. Значение `fail` используется по умолчанию и приводит к ошибке, если одна или несколько групп не существуют. Значение `ignore` игнорирует несуществующие группы. Значение `warn` выводит предупреждение для каждой несуществующей группы, но продолжает выполнение без ошибки. Варианты: `"fail"` ← (по умолчанию) `"ignore"` `"warn"`
permissions_failure_action string добавлено в microsoft.ad 1.8.0	Определяет поведение, если пользователь, указанный в `domain_username`, не может изменить группу, указанную в `groups`. Значение `fail` используется по умолчанию и приводит к ошибке, если пользователь не может изменить членство в какой-либо группе. Значение `ignore` игнорирует группы, которые невозможно изменить. Значение `warn` выводит предупреждение для каждой группы, которую невозможно изменить, но продолжает выполнение без ошибки. Варианты: `"fail"` ← (по умолчанию) `"ignore"` `"warn"`
remove list / элементы=any	Группы, из которых нужно удалить пользователя.
set list / элементы=any	Список групп, членом которых является пользователь. Группы, не указанные в списке, будут удалены из существующего списка. Укажите пустой список, чтобы удалить пользователя из всех групп.
identity string	Идентификатор объекта AD, используемый для поиска управляемого объекта 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.
password string	При необходимости задает пароль пользователя этим значением в открытом виде. Чтобы включить учетную запись (enabled), для нее уже должен быть задан пароль либо здесь необходимо указать пароль. Используйте параметр update_password, чтобы задать способ проверки пароля на идемпотентность.
password_expired boolean	Значение `yes` потребует от пользователя сменить пароль при следующем входе в систему. Значение `no` сбрасывает флаг истечения срока действия пароля. Этот параметр нельзя использовать одновременно с password_never_expires. Варианты: `false` `true`
password_never_expires boolean	Значение `yes` задает пароль, срок действия которого никогда не истекает. Значение `no` разрешает истечение срока действия пароля. Этот параметр нельзя использовать одновременно с password_expired. Варианты: `false` `true`

path string	Путь к подразделению OU или контейнеру, в котором должен находиться новый объект. При создании нового объекта он будет создан по указанному пути. Если путь не указан, для большинства типов объектов в качестве пути будет использоваться `defaultNamingContext` домена. При управлении существующим объектом, найденным по параметру identity, найденный объект будет перемещён по пути, указанному в этом параметре. Если путь не указан, объект перемещён не будет. Модули microsoft.ad.computer, microsoft.ad.user и microsoft.ad.group используют собственный путь по умолчанию, настроенный на контроллере домена Active Directory. В качестве значения можно указать литерал `microsoft.ad.default_path` — он соответствует значению по умолчанию, используемому при создании нового объекта.
postal_code string	Настраивает почтовый индекс пользователя. Это значение атрибута LDAP `postalcode`.
protect_from_deletion boolean	Защищает объект от случайного удаления. Для обычного удаления объекта устанавливается запрет на доступ. Прежде чем удалить объект через графический интерфейс или любой другой инструмент вне Ansible, необходимо снять эту защиту. Использование state=absent всё равно удалит объект AD, даже если он защищён от удаления. Допустимые значения: `false` `true`
sam_account_name string	Значение `sAMAccountName`, задаваемое для пользователя. Если параметр не указан, при создании нового пользователя используется значение name.
spn псевдонимы: spns dictionary	Указывает имена субъектов-служб, которые нужно добавить, удалить или задать для учётной записи. Это значение атрибута LDAP `servicePrincipalName`. Чтобы удалить все имена субъектов-служб, используйте set с пустым списком. Дополнительные сведения о добавлении, удалении и задании значений параметров-списков см. в разделе Задание значений параметров-списков.
add list / elements=string	Имена SPN, которые нужно добавить в `servicePrincipalName`.
remove list / elements=string	Имена SPN, которые нужно удалить из `servicePrincipalName`.
set list / elements=string	Имена SPN, которые нужно задать как единственные значения в `servicePrincipalName`. Все существующие имена SPN, отсутствующие в указанном списке, будут удалены. Чтобы удалить все имена SPN объекта AD, задайте пустой список.
state string	Укажите `present`, чтобы обеспечить существование объекта AD. Укажите `absent`, чтобы удалить объект AD, если он существует. При state=present необходимо задать параметр name. При использовании `absent` объект AD и все дочерние объекты будут рекурсивно удалены, если объект является контейнером. Объект AD также будет удалён, даже если он защищён от случайного удаления. Допустимые значения: `"absent"` `"present"` ← (по умолчанию)
state_province string	Настраивает штат или регион пользователя. Это значение атрибута LDAP `state`.
street string	Настраивает адрес пользователя. Это значение атрибута LDAP `streetaddress`.
surname псевдонимы: lastname string	Настраивает фамилию пользователя. Это значение атрибута LDAP `sn`.
update_password string	`always` всегда обновляет пароли. `on_create` устанавливает пароль только для вновь созданных пользователей. `when_changed` устанавливает пароль только при его изменении. Использование `when_changed` не будет работать, если учётная запись не включена или срок её действия истёк. Допустимые значения: `"always"` ← (по умолчанию) `"on_create"` `"when_changed"`
upn string	Настраивает имя участника-пользователя (UPN) для учётной записи. Этот параметр не является обязательным, но для современных версий Active Directory рекомендуется задавать его. Формат: `<username>@<domain>`. Это значение атрибута LDAP `userPrincipalName`.
user_cannot_change_password boolean	`yes` запрещает пользователю менять пароль. `no` разрешает пользователю менять пароль. Допустимые значения: `false` `true`

Атрибуты

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

Примечания

Примечание

Инструкции по переходу с community.windows.win_domain_user на этот модуль см. в разделе Переход с win_domain_user.
Этот модуль необходимо запускать на целевом хосте 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.group: Управляет объектами групп Active Directory.
microsoft.ad.object: Управляет объектами Active Directory.
microsoft.ad.object_info: Собирает сведения об объекте Active Directory.
microsoft.ad.computer: Управляет объектами компьютеров Active Directory.
Руководство по переходу: Этот модуль заменяет community.windows.win_domain_user. Подробности см. в руководстве по переходу.
community.windows.win_domain_user: Официальная документация по модулю community.windows.win_domain_user.

Примеры

- name: Ensure user bob is present with address information
  microsoft.ad.user:
    identity: bob
    firstname: Bob
    surname: Smith
    company: BobCo
    password: B0bP4ssw0rd
    state: present
    groups:
      set:
        - Domain Admins
    street: 123 4th St.
    city: Sometown
    state_province: IN
    postal_code: 12345
    country: US
    attributes:
      set:
        telephoneNumber: 555-123456

- name: Ensure user bob is created and use custom credentials to create the user
  microsoft.ad.user:
    identity: bob
    firstname: Bob
    surname: Smith
    password: B0bP4ssw0rd
    state: present
    domain_username: DOMAIN\admin-account
    domain_password: SomePas2w0rd
    domain_server: domain@DOMAIN.COM

- name: Ensure user bob is present in OU ou=test,dc=domain,dc=local
  microsoft.ad.user:
    identity: bob
    password: B0bP4ssw0rd
    state: present
    path: ou=test,dc=domain,dc=local
    groups:
      set:
        - Domain Admins
        - Domain Users

- name: Ensure user bob is absent
  microsoft.ad.user:
    identity: bob
    state: absent

- name: Ensure user has only these spn's defined
  microsoft.ad.user:
    identity: liz.kenyon
    spn:
      set:
        - MSSQLSvc/us99db-svr95:1433
        - MSSQLSvc/us99db-svr95.vmware.com:1433

- name: Ensure user has spn added
  microsoft.ad.user:
    identity: liz.kenyon
    spn:
      add:
        - MSSQLSvc/us99db-svr95:2433

- name: Ensure user is created with delegates and spn's defined
  microsoft.ad.user:
    identity: shmemmmy
    password: The3rubberducki33!
    state: present
    groups:
      set:
        - Domain Admins
        - Domain Users
        - Enterprise Admins
    delegates:
      set:
        - CN=shenetworks,CN=Users,DC=ansible,DC=test
        - CN=mk.ai,CN=Users,DC=ansible,DC=test
        - CN=jessiedotjs,CN=Users,DC=ansible,DC=test
    spn:
      set:
        - MSSQLSvc/us99db-svr95:2433

# The name option is the name of the AD object as seen in dsa.msc and not the
# sAMAccountName. For example, this will change the sAMAccountName of the user
# CN=existing_user,CN=Users,DC=domain,DC=com to 'new_sam_name'.
# E.g. This will change
- name: Change the user's sAMAccountName
  microsoft.ad.user:
    name: existing_user
    sam_account_name: new_sam_name
    state: present

# This will rename the AD object that is specified by identity to 'new_name'.
# The identity value can be the object's GUID, SecurityIdentifier, or
# sAMAccountName. It is important to use the identity value when renaming or
# moving a user object to ensure the object is moved/renamed rather than a new
# one being created.
- name: Rename user LDAP name
  microsoft.ad.user:
    name: new_name
    identity: '{{ user_obj.object_guid }}'
    state: present

# Like changing the name example above, the identity option is needed to ensure
# the existing user object specified is moved rather than a new one created at
# the path specified.
- name: Move user object to different OU
  microsoft.ad.user:
    name: user
    path: OU=Admins,DC=domain,DC=com
    identity: '{{ user_obj.sid }}'
    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"`
sid string	Идентификатор безопасности (SID) управляемой учётной записи. Если в режиме check mode был создан новый пользователь, значение SID будет `S-1-5-0000`. Возвращается: всегда Пример: `"S-1-5-21-4151808797-3430561092-2843464588-1104"`

Авторы

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/user_module.html