community.windows.win_domain_user – Manages Windows Active Directory user accounts

Note

This plugin is part of the community.windows collection (version 1.8.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.windows.

To use it in a playbook, specify: community.windows.win_domain_user.

Synopsis

  • Manages Windows Active Directory user accounts.

Parameters

Parameter

Comments

account_locked

string

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.

Choices:

  • False

attributes

string

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

The password for username.

domain_server

string

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

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

yes will enable the user account.

no will disable the account.

Choices:

  • no

  • yes ← (default)

firstname

string

Configures the user’s first name (given name).

groups

list / elements=string

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

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.

Choices:

  • add

  • remove

  • replace ← (default)

identity

string

Identity parameter used to find the User in the Active Directory.

This value can be in the forms Distinguished Name, objectGUID, objectSid or sAMAccountName.

Default to name if not set.

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

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.

Choices:

  • no

  • yes

password_never_expires

boolean

yes will set the password to never expire.

no will allow the password to expire.

This is mutually exclusive with password_expired.

Choices:

  • no

  • yes

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.

sam_account_name

string

added in 1.7.0 of community.windows

Configures the SAM Account Name (sAMAccountName) for the account.

This is allowed to a maximum of 20 characters due to pre-Windows 2000 restrictions.

Default to the <username> specified in upn or name if not set.

state

string

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.

Choices:

  • absent

  • present ← (default)

  • query

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

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.

Choices:

  • always ← (default)

  • on_create

  • when_changed

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

yes will prevent the user from changing their password.

no will allow the user to change their password.

Choices:

  • no

  • yes

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

ansible.windows.win_domain

The official documentation on the ansible.windows.win_domain module.

ansible.windows.win_domain_controller

The official documentation on the ansible.windows.win_domain_controller module.

community.windows.win_domain_computer

The official documentation on the community.windows.win_domain_computer module.

community.windows.win_domain_group

The official documentation on the community.windows.win_domain_group module.

ansible.windows.win_domain_membership

The official documentation on the ansible.windows.win_domain_membership module.

ansible.windows.win_user

The official documentation on the ansible.windows.win_user module.

community.windows.win_user_profile

The official documentation on the community.windows.win_user_profile module.

Examples

- name: Ensure user bob is present with address information
  community.windows.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
  community.windows.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
  community.windows.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
  community.windows.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

Description

account_locked

boolean

true if the account is locked

Returned: always

Sample: false

changed

boolean

true if the account changed during execution

Returned: always

Sample: false

city

string

The user city

Returned: always

Sample: “Indianapolis”

company

string

The user company

Returned: always

Sample: “RedHat”

country

string

The user country

Returned: always

Sample: “US”

created

boolean

Whether a user was created

Returned: always

Sample: true

description

string

A description of the account

Returned: always

Sample: “Server Administrator”

distinguished_name

string

DN of the user account

Returned: always

Sample: “CN=nick,OU=test,DC=domain,DC=local”

email

string

The user email address

Returned: always

Sample: “nick@domain.local”

enabled

string

true if the account is enabled and false if disabled

Returned: always

Sample: true

firstname

string

The user first name

Returned: always

Sample: “Nick”

groups

list / elements=string

AD Groups to which the account belongs

Returned: always

Sample: [“Domain Admins”, “Domain Users”]

msg

string

Summary message of whether the user is present or absent

Returned: always

Sample: “User nick is present”

name

string

The username on the account

Returned: always

Sample: “nick”

password_expired

boolean

true if the account password has expired

Returned: always

Sample: false

password_updated

boolean

true if the password changed during this execution

Returned: always

Sample: true

postal_code

string

The user postal code

Returned: always

Sample: 46033

sam_account_name

string

added in 1.7.0 of community.windows

The SAM Account Name of the account

Returned: always

Sample: “nick”

sid

string

The SID of the account

Returned: always

Sample: “S-1-5-21-2752426336-228313920-2202711348-1175”

state

string

The state of the user account

Returned: always

Sample: “present”

state_province

string

The user state or province

Returned: always

Sample: “IN”

street

string

The user street address

Returned: always

Sample: “123 4th St.”

surname

string

The user last name

Returned: always

Sample: “Doe”

upn

string

The User Principal Name of the account

Returned: always

Sample: “nick@domain.local”

user_cannot_change_password

string

true if the user is not allowed to change password

Returned: always

Sample: false

Authors

  • Nick Chandler (@nwchandler)