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
Parameters
Notes
See Also
Examples
Return Values

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.

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

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_user_module.html