salt.modules.win_shadow#

Manage the shadow file

Important

If you feel that Salt should be using this module to manage passwords on a minion, and it is using a different module (or gives an error similar to 'shadow.info' is not available), see here.

depends:

  • pywintypes

  • win32security

  • winerror

salt.modules.win_shadow.info(name)#

Return information for the specified user.

Note

This just returns dummy data so that salt states can work.

Parameters:

name (str) -- The name of the user account to show.

CLI Example:

salt '*' shadow.info root
salt.modules.win_shadow.require_password_change(name)#

Require the user to change their password the next time they log in.

Parameters:

name (str) -- The name of the user account to require a password change.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' shadow.require_password_change <username>
salt.modules.win_shadow.set_expire(name, expire)#

Set the expiration date for a user account.

Parameters:

  • name (str) -- The name of the user account to edit.

  • expire (str) -- The date the account will expire.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' shadow.set_expire <username> 2016/7/1
salt.modules.win_shadow.set_password(name, password)#

Set the password for a named user.

Parameters:

  • name (str) -- The name of the user account.

  • password (str) -- The new password.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' shadow.set_password root mysecretpassword
salt.modules.win_shadow.unlock_account(name)#

Unlocks a user account.

Parameters:

name (str) -- The name of the user account to unlock.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' shadow.unlock_account <username>
salt.modules.win_shadow.verify_password(name, password)#

Verify the password for a Windows user account by attempting a network logon. This uses LOGON32_LOGON_NETWORK which does not create an interactive session and typically does not generate audit log events.

Note

This is Microsoft's documented recommended method for validating credentials on Windows. There is no equivalent of /etc/shadow on Windows — the NT hash stored in the SAM database is inaccessible even to SYSTEM at runtime. LogonUser with LOGON32_LOGON_NETWORK is the only supported approach.

See How to validate user credentials on Microsoft operating systems

Warning

A wrong password will increment the account's bad-logon counter. If the counter reaches the lockout threshold, the account will be locked. This function detects that situation and automatically unlocks the account if the lockout was caused by this call (i.e. the account was not already locked beforehand). If the account was already locked, a CommandExecutionError is raised because the password cannot be verified in that state.

If the logon attempt causes the account to become locked (i.e. the bad password pushed the counter over the threshold), the account is automatically unlocked — but only if it was not already locked before this call.

Parameters:

  • name (str) -- The username to verify. Accepts plain names (local accounts), UPN format (user@domain), or down-level format (DOMAIN\user).

  • password (str) -- The password to verify.

Returns:

True if the password is correct (or correct but the account has some other restriction such as being disabled or expired). False if the password is wrong.

Return type:

bool

Raises:

CommandExecutionError -- If the account is locked (cannot verify) or an unexpected error occurs.

CLI Example:

salt '*' shadow.verify_password <username> <password>