win_domain_user - Manages Windows Active Directory user accounts

New in version 2.4.

Synopsis

  • Manages Windows Active Directory user accounts.

Options

parameter required default choices comments
account_locked
 no
  • yes
  • no
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 'enabled' to 'no'.
city
 no
Configures the user's city
company
 no
Configures the user's company name
country
 no
Configures the user's country code. Note that this is a two-character ISO 3166 code.
description
 no
Description of the user
email
 no
Configures the user's email address. This is a record in AD and does not do anything to configure any email servers or systems.
enabled
 no yes
  • yes
  • no
yes will enable the user account. no will disable the account.
firstname
 no
Configures the user's first name (given name)
groups
 no
Adds or removes the user from this list of groups, depending on the value of groups_action. To remove all but the Principal Group, set groups=<principal group name> and groups_action=replace. Note that users cannot be removed from their principal group (for example, "Domain Users").
groups_action
 no replace
  • replace
  • add
  • remove
If replace, the user is added as a member of each group in groups and removed from any other groups. If add, the user is added to each group in groups where not already a member. If remove, the user is removed from each group in groups.
name
 yes
Name of the user to create, remove or modify.
password
 no
Optionally set the user's password to this (plain text) value. In order to enable an account - enabled - a password must already be configured on the account, or you must provide a password here.
password_expired
 no
  • yes
  • no
yes will require the user to change their password at next login. no will clear the expired password flag. This is mutually exclusive with password_never_expires.
password_never_expires
 no
  • yes
  • no
yes will set the password to never expire. no will allow the password to expire. This is mutually exclusive with password_expired
path
 no
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., state=absent) the user and then re-add the user with the appropriate path.
postal_code
 no
Configures the user's postal code / zip code
state
 no present
  • present
  • absent
  • query
When present, creates or updates the user account. When absent, removes the user account if it exists. When query, retrieves the user account details without making any changes.
state_province
 no
Configures the user's state or province
street
 no
Configures the user's street address
surname
 no
Configures the user's last name (surname)
update_password
 no always
  • always
  • on_create
always will update passwords if they differ. on_create will only set the password for newly created users. Note that always will always report an Ansible status of 'changed' because we cannot determine whether the new password differs from the old password.
upn
 no
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 "<username>@<domain>".
user_cannot_change_password
 no
  • yes
  • no
yes will prevent the user from changing their password. no will allow the user to change their password.

Examples

- 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

- 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

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
account_locked
true if the account is locked
 always boolean False
changed
true if the account changed during execution
 always boolean False
city
The user city
 always string Indianapolis
company
The user company
 always string RedHat
country
The user country
 always string US
description
A description of the account
 always string Server Administrator
distinguished_name
DN of the user account
 always string CN=nick,OU=test,DC=domain,DC=local
email
The user email address
 always string [email protected]
enabled
true if the account is enabled and false if disabled
 always string True
firstname
The user first name
 always string Nick
groups
AD Groups to which the account belongs
 always list ['Domain Admins', 'Domain Users']
msg
Summary message of whether the user is present or absent
 always string User nick is present
name
The username on the account
 always string nick
password_expired
true if the account password has expired
 always boolean False
password_updated
true if the password changed during this execution
 always boolean True
postal_code
The user postal code
 always string 46033
sid
The SID of the account
 always string S-1-5-21-2752426336-228313920-2202711348-1175
state
The state of the user account
 always string present
state_province
The user state or province
 always string IN
street
The user street address
 always string 123 4th St.
surname
The user last name
 always string Doe
upn
The User Principal Name of the account
 always string [email protected]
user_cannot_change_password
true if the user is not allowed to change password
 always string False

Notes

Note

  • Works with Windows 2012R2 and newer.
  • If running on a server that is not a Domain Controller, credential delegation through CredSSP or Kerberos with delegation must be used.
  • Note that some individuals have confirmed successful operation on Windows 2008R2 servers with AD and AD Web Services enabled, but this has not received the same degree of testing as Windows 2012R2.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/win_domain_user_module.html