ansible.windows.win_user module – Manages local Windows user accounts

Note

This module is part of the ansible.windows collection (version 2.5.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 ansible.windows.

To use it in a playbook, specify: ansible.windows.win_user.

Synopsis

• Manages local Windows user accounts.

• For non-Windows targets, use the ansible.builtin.user module instead.

Parameters

Parameter	Comments
account_disabled boolean	true will disable the user account. false will clear the disabled flag. Choices: false true
account_expires string added in ansible.windows 2.4.0	Set the account expiration date for the user. This value should be in the format %Y-%m-%d or %Y-%m-%dT%H:%M:%S%z. The timezone can be omitted in the long format and will default to UTC. The format of %z is ±HHMM, ±HH:MM, or Z for UTC. Set the value to never to remove the account expiration date.
account_locked boolean	Only false can be set and it will unlock the user account if locked. Choices: false true
description string	Description of the user.
fullname string	Full name of the user.
groups list / elements=string	Adds or removes the user from this comma-separated list of groups, depending on the value of groups_action. When groups_action is replace and groups is set to the empty string (‘groups=’), the user is removed from all groups. Since ansible.windows v1.5.0 it is possible to specify a group using it’s security identifier.
groups_action string	If add, the user is added to each group in groups where not already a member. If replace, the user is added as a member of each group in groups and removed from any other groups. If remove, the user is removed from each group in groups. Choices: "add" "replace" ← (default) "remove"
home_directory string added in ansible.windows 1.0.0	The designated home directory of the user.
login_script string added in ansible.windows 1.0.0	The login script of the user.
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.
password_expired boolean	true will require the user to change their password at next login. false will clear the expired password flag. Choices: false true
password_never_expires boolean	true will set the password to never expire. false will allow the password to expire. Choices: false true
profile string added in ansible.windows 1.0.0	The profile path of the user.
state string	When absent, removes the user account if it exists. When present, creates or updates the user account. When query, retrieves the user account details without making any changes. Choices: "absent" "present" ← (default) "query"
update_password string	always will update passwords if they differ. on_create will only set the password for newly created users. Choices: "always" ← (default) "on_create"
user_cannot_change_password boolean	true will prevent the user from changing their password. false will allow the user to change their password. Choices: false true

Notes

Note

• The return values are based on the user object after the module options have been set. When running in check mode the values will still reflect the existing user settings and not what they would have been changed to.

See Also

See also

ansible.builtin.user

Manage user accounts.

ansible.windows.win_domain_membership

Manage domain/workgroup membership for a Windows host.

community.windows.win_domain_user

Manages Windows Active Directory user accounts.

ansible.windows.win_group

Add and remove local groups.

ansible.windows.win_group_membership

Manage Windows local group membership.

community.windows.win_user_profile

Manages the Windows user profiles.

Examples

- name: Ensure user bob is present
  ansible.windows.win_user:
    name: bob
    password: B0bP4ssw0rd
    state: present
    groups:
      - Users

- name: Ensure user bob is absent
  ansible.windows.win_user:
    name: bob
    state: absent

- name: Set an account expiration date to the 27th of October 2024 at 2:30PM UTC
  ansible.windows.win_user:
    name: bob
    state: present
    account_expires: '2024-10-27T14:30:00Z'

- name: Set an account expiration 30 days in the future
  ansible.windows.win_user:
    name: bob
    state: present
    account_expires: '{{ "%Y-%m-%dT%H:%M:%S%z" | ansible.builtin.strftime(now().timestamp() + (60 * 60 * 24 * 30)) }}'

- name: Remove account expiration date
  ansible.windows.win_user:
    name: bob
    state: present
    account_expires: never

Return Values

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

Key	Description
account_disabled boolean	Whether the user is disabled. Returned: user exists Sample: false
account_locked boolean	Whether the user is locked. Returned: user exists Sample: false
description string	The description set for the user. Returned: user exists Sample: "Username for test"
fullname string	The full name set for the user. Returned: user exists Sample: "Test Username"
groups list / elements=string	A list of groups and their ADSI path the user is a member of. Returned: user exists Sample: [{"name": "Administrators", "path": "WinNT://WORKGROUP/USER-PC/Administrators"}]
name string	The name of the user Returned: always Sample: "username"
password_expired boolean	Whether the password is expired. Returned: user exists Sample: false
password_never_expires boolean	Whether the password is set to never expire. Returned: user exists Sample: true
path string	The ADSI path for the user. Returned: user exists Sample: "WinNT://WORKGROUP/USER-PC/username"
sid string	The SID for the user. Returned: user exists Sample: "S-1-5-21-3322259488-2828151810-3939402796-1001"
user_cannot_change_password boolean	Whether the user can change their own password. Returned: user exists Sample: false

Authors

• Paul Durivage (@angstwad)

• Chris Church (@cchurch)

Collection links

• Issue Tracker
• Repository (Sources)
• Communication