win_domain_user – Manages Windows Active Directory user accounts — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_domain_user – Manages Windows Active Directory user accounts

New in version 2.4.

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## 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 string 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 string |  | Configures the user's city.
company string |  | Configures the user's company name.
country string |  | Configures the user's country code. Note that this is a two-character ISO 3166 code.
description string |  | Description of the user
domain_password string added in 2.5 |  | The password for username.
domain_server string 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 string 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 string |  | 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 string |  | 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 string | 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 string / required |  | Name of the user to create, remove or modify.
password string |  | Optionally set the user's password to this (plain text) value. 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 string |  | 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 string |  | Configures the user's postal code / zip code.
state string | 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 string |  | Configures the user's state or province.
street string |  | Configures the user's street address.
surname string |  | Configures the user's last name (surname).
update_password string | Choices: always ← on_create when_changed | `always` will always update passwords. `on_create` will only set the password for newly created users. `when_changed` will only set the password when changed (added in ansible 2.9).
upn string |  | 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.

## See Also

See also

win_domain – Ensures the existence of a Windows domain
  The official documentation on the win_domain module.
win_domain_controller – Manage domain controller/member server state for a Windows host
  The official documentation on the win_domain_controller module.
win_domain_computer – Manage computers in Active Directory
  The official documentation on the win_domain_computer module.
win_domain_group – Creates, modifies or removes domain groups
  The official documentation on the win_domain_group module.
win_domain_membership – Manage domain/workgroup membership for a Windows host
  The official documentation on the win_domain_membership module.
win_user – Manages local Windows user accounts
  The official documentation on the win_user module.
win_user_profile – Manages the Windows user profiles
  The official documentation on the win_user_profile module.

## 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: 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

## 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
created boolean | always | Whether a user was created Sample: True
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: nick@domain.local
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: nick@domain.local
user_cannot_change_password string | always | true if the user is not allowed to change password

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Nick Chandler (@nwchandler)

Hint

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