win_user - Manages local Windows user accounts¶

New in version 1.7.

Synopsis
Parameters
Notes
Examples
Return Values
Status
Maintenance
- Support
- Author

Synopsis ¶

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

Parameters ¶

Parameter	Choices/Defaults	Comments
account_disabled bool (added in 1.9)	Choices: no yes	`yes` will disable the user account. `no` will clear the disabled flag.
account_locked (added in 1.9)	Choices: 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)	Choices: 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 bool (added in 1.9)	Choices: no yes	`yes` will require the user to change their password at next login. `no` will clear the expired password flag.
password_never_expires bool (added in 1.9)	Choices: no yes	`yes` will set the password to never expire. `no` will allow the password to expire.
state	Choices: 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)	Choices: 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 bool (added in 1.9)	Choices: 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 bool	user exists	Whether the user is disabled.
account_locked bool	user exists	Whether the user is locked.
description str	user exists	The description set for the user. Sample: Username for test
fullname str	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: [{'path': 'WinNT://WORKGROUP/USER-PC/Administrators', 'name': 'Administrators'}]
name str	always	The name of the user Sample: username
password_expired bool	user exists	Whether the password is expired.
password_never_expires bool	user exists	Whether the password is set to never expire. Sample: True
path str	user exists	The ADSI path for the user. Sample: WinNT://WORKGROUP/USER-PC/username
sid str	user exists	The SID for the user. Sample: S-1-5-21-3322259488-2828151810-3939402796-1001
user_cannot_change_password bool	user exists	Whether the user can change their own password.

Status ¶

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance ¶

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

Support ¶

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author ¶

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

Hint

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