win_user – Manages local Windows user accounts

From Get docs
Ansible/docs/2.7/modules/win user module


win_user – Manages local Windows user accounts

New in version 1.7.


Synopsis

  • Manages local Windows user accounts.
  • For non-Windows targets, use the user module instead.

Parameters

Parameter Choices/Defaults Comments

account_disabled

boolean

added in 1.9

  • no
  • yes

yes will disable the user account.

no will clear the disabled flag.

account_locked

-

added in 1.9

  • no

no will unlock the user account if locked.

description

-

added in 1.9

Description of the user.

fullname

-

added in 1.9

Full name of the user.

groups

-

added in 1.9

Adds or removes the user from this comma-separated lis 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.

groups_action

-

added in 1.9

  • add
  • replace

  • remove

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.

name

- / required

Name of the user to create, remove or modify.

password

-

Optionally set the user's password to this (plain text) value.

password_expired

boolean

added in 1.9

  • no
  • yes

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

no will clear the expired password flag.

password_never_expires

boolean

added in 1.9

  • no
  • yes

yes will set the password to never expire.

no will allow the password to expire.

state

-

  • absent
  • present

  • query

When absent, removes the user account if it exists.

When present, creates or updates the user account.

When query (new in 1.9), retrieves the user account details without making any changes.

update_password

-

added in 1.9

  • always

  • on_create

always will update passwords if they differ. on_create will only set the password for newly created users.

user_cannot_change_password

boolean

added in 1.9

  • no
  • yes

yes will prevent the user from changing their password.

no will allow the user to change their password.



Notes

Note

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


Examples

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

- name: Ensure user bob is absent
  win_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_disabled

boolean

user exists

Whether the user is disabled.


account_locked

boolean

user exists

Whether the user is locked.


description

string

user exists

The description set for the user.


Sample:

Username for test

fullname

string

user exists

The full name set for the user.


Sample:

Test Username

groups

list

user exists

A list of groups and their ADSI path the user is a member of.


Sample:

[{'name': 'Administrators', 'path': 'WinNT://WORKGROUP/USER-PC/Administrators'}]

name

string

always

The name of the user


Sample:

username

password_expired

boolean

user exists

Whether the password is expired.


password_never_expires

boolean

user exists

Whether the password is set to never expire.


Sample:

True

path

string

user exists

The ADSI path for the user.


Sample:

WinNT://WORKGROUP/USER-PC/username

sid

string

user exists

The SID for the user.


Sample:

S-1-5-21-3322259488-2828151810-3939402796-1001

user_cannot_change_password

boolean

user exists

Whether the user can change their own password.





Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • Paul Durivage (@angstwad)
  • Chris Church (@cchurch)

Hint

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


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