ansible / ansible.builtin / v2.9.27 / module / win_domain_user Manages Windows Active Directory user accounts | "added in version" 2.4 of ansible.builtin" Authors: Nick Chandler (@nwchandler) preview | supported by communityansible.builtin.win_domain_user (v2.9.27) — module
pip
Install with pip install ansible==2.9.27
Manages Windows Active Directory user accounts.
- name: Ensure user bob is present with address information win_domain_user: name: bob firstname: Bob surname: Smith company: BobCo password: B0bP4ssw0rd state: present groups: - Domain Admins street: 123 4th St. city: Sometown state_province: IN postal_code: 12345 country: US attributes: telephoneNumber: 555-123456
- name: Ensure user bob is created and use custom credentials to create the user win_domain_user: name: 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 win_domain_user: name: bob password: B0bP4ssw0rd state: present path: ou=test,dc=domain,dc=local groups: - Domain Admins
- name: Ensure user bob is absent win_domain_user: name: bob state: absent
upn: description: - Configures the User Principal Name (UPN) for the account. - This is not required, but is best practice to configure for modern versions of Active Directory. - The format is C(<username>@<domain>). type: str city: description: - Configures the user's city. type: str name: description: - Name of the user to create, remove or modify. required: true type: str path: description: - Container or OU for the new user; if you do not specify this, the user will be placed in the default container for users in the domain. - Setting the path is only available when a new user is created; if you specify a path on an existing user, the user's path will not be updated - you must delete (e.g., C(state=absent)) the user and then re-add the user with the appropriate path. type: str email: description: - Configures the user's email address. - This is a record in AD and does not do anything to configure any email servers or systems. type: str state: choices: - absent - present - query default: present description: - When C(present), creates or updates the user account. - When C(absent), removes the user account if it exists. - When C(query), retrieves the user account details without making any changes. type: str groups: description: - Adds or removes the user from this list of groups, depending on the value of I(groups_action). - To remove all but the Principal Group, set C(groups=<principal group name>) and I(groups_action=replace). - Note that users cannot be removed from their principal group (for example, "Domain Users"). type: list street: description: - Configures the user's street address. type: str company: description: - Configures the user's company name. type: str country: description: - Configures the user's country code. - Note that this is a two-character ISO 3166 code. type: str enabled: default: true description: - C(yes) will enable the user account. - C(no) will disable the account. type: bool surname: description: - Configures the user's last name (surname). type: str password: description: - Optionally set the user's password to this (plain text) value. - To enable an account - I(enabled) - a password must already be configured on the account, or you must provide a password here. type: str firstname: description: - Configures the user's first name (given name). type: str attributes: description: - A dict of custom LDAP attributes to set on the user. - This can be used to set custom attributes that are not exposed as module parameters, e.g. C(telephoneNumber). - See the examples on how to format this parameter. type: str version_added: '2.5' version_added_collection: ansible.builtin description: description: - Description of the user type: str postal_code: description: - Configures the user's postal code / zip code. type: str domain_server: description: - Specifies the Active Directory Domain Services instance to connect to. - Can be in the form of an FQDN or NetBIOS name. - If not specified then the value is based on the domain of the computer running PowerShell. type: str version_added: '2.5' version_added_collection: ansible.builtin groups_action: choices: - add - remove - replace default: replace description: - If C(add), the user is added to each group in I(groups) where not already a member. - If C(remove), the user is removed from each group in I(groups). - If C(replace), the user is added as a member of each group in I(groups) and removed from any other groups. type: str account_locked: choices: - false description: - C(no) will unlock the user account if locked. - Note that there is not a way to lock an account as an administrator. - Accounts are locked due to user actions; as an admin, you may only unlock a locked account. - If you wish to administratively disable an account, set I(enabled) to C(no). state_province: description: - Configures the user's state or province. type: str domain_password: description: - The password for I(username). type: str version_added: '2.5' version_added_collection: ansible.builtin domain_username: description: - The username to use when interacting with AD. - If this is not set then the user Ansible used to log in with will be used instead when using CredSSP or Kerberos with credential delegation. type: str version_added: '2.5' version_added_collection: ansible.builtin update_password: choices: - always - on_create - when_changed default: always description: - C(always) will always update passwords. - C(on_create) will only set the password for newly created users. - C(when_changed) will only set the password when changed (added in ansible 2.9). type: str password_expired: description: - C(yes) will require the user to change their password at next login. - C(no) will clear the expired password flag. - This is mutually exclusive with I(password_never_expires). type: bool password_never_expires: description: - C(yes) will set the password to never expire. - C(no) will allow the password to expire. - This is mutually exclusive with I(password_expired). type: bool user_cannot_change_password: description: - C(yes) will prevent the user from changing their password. - C(no) will allow the user to change their password. type: bool
account_locked: description: true if the account is locked returned: always sample: false type: bool changed: description: true if the account changed during execution returned: always sample: false type: bool city: description: The user city returned: always sample: Indianapolis type: str company: description: The user company returned: always sample: RedHat type: str country: description: The user country returned: always sample: US type: str created: description: Whether a user was created returned: always sample: true type: bool description: description: A description of the account returned: always sample: Server Administrator type: str distinguished_name: description: DN of the user account returned: always sample: CN=nick,OU=test,DC=domain,DC=local type: str email: description: The user email address returned: always sample: nick@domain.local type: str enabled: description: true if the account is enabled and false if disabled returned: always sample: true type: str firstname: description: The user first name returned: always sample: Nick type: str groups: description: AD Groups to which the account belongs returned: always sample: - Domain Admins - Domain Users type: list msg: description: Summary message of whether the user is present or absent returned: always sample: User nick is present type: str name: description: The username on the account returned: always sample: nick type: str password_expired: description: true if the account password has expired returned: always sample: false type: bool password_updated: description: true if the password changed during this execution returned: always sample: true type: bool postal_code: description: The user postal code returned: always sample: 46033 type: str sid: description: The SID of the account returned: always sample: S-1-5-21-2752426336-228313920-2202711348-1175 type: str state: description: The state of the user account returned: always sample: present type: str state_province: description: The user state or province returned: always sample: IN type: str street: description: The user street address returned: always sample: 123 4th St. type: str surname: description: The user last name returned: always sample: Doe type: str upn: description: The User Principal Name of the account returned: always sample: nick@domain.local type: str user_cannot_change_password: description: true if the user is not allowed to change password returned: always sample: false type: str