win_domain_user – Manages Windows Active Directory user accounts

New in version 2.4.

Synopsis

  • Manages Windows Active Directory user accounts.

Parameters

Parameter Choices/Defaults Comments
account_locked
-
    Choices:
  • 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.
attributes
-
added in 2.5
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. telephoneNumber.
See the examples on how to format this parameter.
city
-
Configures the user's city.
company
-
Configures the user's company name.
country
-
Configures the user's country code.
Note that this is a two-character ISO 3166 code.
description
-
Description of the user
domain_password
-
added in 2.5
The password for username.
domain_server
-
added in 2.5
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.
domain_username
-
added in 2.5
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.
email
-
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
boolean
    Choices:
  • no
  • yes ←
yes will enable the user account.
no will disable the account.
firstname
-
Configures the user's first name (given name).
groups
list
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
-
    Choices:
  • add
  • remove
  • replace ←
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.
If replace, the user is added as a member of each group in groups and removed from any other groups.
name
- / required
Name of the user to create, remove or modify.
password
-
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
boolean
    Choices:
  • no
  • yes
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
boolean
    Choices:
  • no
  • yes
yes will set the password to never expire.
no will allow the password to expire.
This is mutually exclusive with password_expired.
path
-
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
-
Configures the user's postal code / zip code.
state
-
    Choices:
  • absent
  • present ←
  • 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
-
Configures the user's state or province.
street
-
Configures the user's street address.
surname
-
Configures the user's last name (surname).
update_password
-
    Choices:
  • 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
-
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
boolean
    Choices:
  • no
  • yes
yes will prevent the user from changing their password.
no will allow the user to change their password.

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 or the domain_username, domain_password must be set.
  • 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.

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
    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: [email protected]

- 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, the following are the fields unique to this module:

Key Returned Description
account_locked
boolean
 always
true if the account is locked
changed
boolean
 always
true if the account changed during execution
city
string
 always
The user city

Sample:
Indianapolis
company
string
 always
The user company

Sample:
RedHat
country
string
 always
The user country

Sample:
US
description
string
 always
A description of the account

Sample:
Server Administrator
distinguished_name
string
 always
DN of the user account

Sample:
CN=nick,OU=test,DC=domain,DC=local
email
string
 always
The user email address

Sample:
enabled
string
 always
true if the account is enabled and false if disabled

Sample:
True
firstname
string
 always
The user first name

Sample:
Nick
groups
list
 always
AD Groups to which the account belongs

Sample:
['Domain Admins', 'Domain Users']
msg
string
 always
Summary message of whether the user is present or absent

Sample:
User nick is present
name
string
 always
The username on the account

Sample:
nick
password_expired
boolean
 always
true if the account password has expired
password_updated
boolean
 always
true if the password changed during this execution

Sample:
True
postal_code
string
 always
The user postal code

Sample:
46033
sid
string
 always
The SID of the account

Sample:
S-1-5-21-2752426336-228313920-2202711348-1175
state
string
 always
The state of the user account

Sample:
present
state_province
string
 always
The user state or province

Sample:
IN
street
string
 always
The user street address

Sample:
123 4th St.
surname
string
 always
The user last name

Sample:
Doe
upn
string
 always
The User Principal Name of the account

Sample:
user_cannot_change_password
string
 always
true if the user is not allowed to change password


Status

Authors

  • Nick Chandler (@nwchandler)

Hint

If you notice any issues in this documentation you can edit this document to improve it.