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

Note

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

yes will disable the user account.

no will clear the disabled flag.

Choices:

  • false

  • true

account_locked

boolean

Only no 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

yes will require the user to change their password at next login.

no will clear the expired password flag.

Choices:

  • false

  • true

password_never_expires

boolean

yes will set the password to never expire.

no 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

yes will prevent the user from changing their password.

no 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

The official documentation on the ansible.builtin.user module.

ansible.windows.win_domain_membership

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

community.windows.win_domain_user

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

ansible.windows.win_group

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

ansible.windows.win_group_membership

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

community.windows.win_user_profile

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

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

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)