Local Accounts Management
Relevant source files
The following files were used as context for generating this wiki page:
- src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs
- test/powershell/Modules/Microsoft.PowerShell.LocalAccounts/Pester.Command.Cmdlets.LocalAccounts.LocalUser.Tests.ps1
- test/powershell/engine/Help/UpdatableHelpSystem.Tests.ps1
- src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs
- README.md
Local Accounts Management is a specialized module within PowerShell designed to facilitate the administration of local security accounts on Windows systems. It provides a standardized interface for creating, configuring, enabling, disabling, and removing local user accounts and groups by interfacing with the system's Security Accounts Manager (SAM).
The module ensures that account operations follow system-level security constraints, such as password complexity requirements and naming conventions. It is implemented primarily through a suite of cmdlets that abstract the underlying SAM API calls into manageable PowerShell commands.
Sources: src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:22-25, test/powershell/Modules/Microsoft.PowerShell.LocalAccounts/Pester.Command.Cmdlets.LocalAccounts.LocalUser.Tests.ps1:60-70
Architecture and Core Components
The architecture of Local Accounts Management follows a provider-consumer pattern where PowerShell cmdlets act as the consumer of the Sam class. The Sam class encapsulates the logic for interacting with the Windows Security Accounts Manager.
The New-LocalUser Cmdlet
The New-LocalUser cmdlet is a representative component of the module, responsible for account creation. It utilizes the NewLocalUserCommand class, which inherits from PSCmdlet. During its lifecycle, it initializes a Sam instance in BeginProcessing and disposes of it in EndProcessing.
Sources: src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:33-40, src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:175-180, src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:225-230
Logic Flow for User Creation
The cmdlet follows a structured execution path to ensure data integrity before calling the SAM API:
- Parameter Validation: Checks for mutually exclusive parameters, such as
AccountExpiresandAccountNeverExpires. - Object Construction: A
LocalUserobject is instantiated and populated with properties likeName,Description, andFullName. - SAM Interaction: The
sam.CreateLocalUsermethod is invoked to commit the new user to the local database.
This diagram illustrates the lifecycle of a user creation request within the NewLocalUserCommand class.
Sources: src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:175-220
Command Suite and Aliases
The module includes a comprehensive set of cmdlets for account lifecycle management. These cmdlets are supported by short-form aliases to improve CLI efficiency.
Available Cmdlets
| Cmdlet | Description | Alias |
|---|---|---|
New-LocalUser | Creates a new local user account. | nlu |
Get-LocalUser | Retrieves local user accounts. | glu |
Set-LocalUser | Modifies properties of a local user. | slu |
Remove-LocalUser | Deletes a local user account. | rlu |
Rename-LocalUser | Renames a local user. | rnlu |
Enable-LocalUser | Enables a disabled local user. | elu |
Disable-LocalUser | Disables a local user. | dlu |
Security and Validation Constraints
Local Accounts Management enforces strict validation rules for user properties to maintain system security and compatibility.
Username Validation
Usernames are subject to several constraints enforced at the parameter level and during command execution:
- Length: Must be between 1 and 20 characters.
- Invalid Characters: Usernames cannot contain characters such as
\ / " [ ] : | < > + = ; , ? *. - Structural Rules: Usernames cannot consist solely of spaces or periods and cannot end with a period.
Sources: src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:115-120, test/powershell/Modules/Microsoft.PowerShell.LocalAccounts/Pester.Command.Cmdlets.LocalAccounts.LocalUser.Tests.ps1:125-165
Parameter Specifications for New-LocalUser
The following table details the primary configuration options available when creating a new local account:
| Parameter | Type | Description |
|---|---|---|
Name | String | Mandatory user name (1-20 chars). |
Password | SecureString | The account password (up to 127 characters). |
NoPassword | Switch | Creates an account without a password. |
AccountExpires | DateTime | Sets an expiration date for the account. |
AccountNeverExpires | Switch | Specifies that the account does not expire. |
Disabled | Switch | Creates the account in a disabled state. |
UserMayNotChangePassword | Switch | Restricts the user from changing their password. |
Sources: src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:55-165
Account Management Data Flow
The data flow within the module typically involves passing a LocalUser object or a Security Identifier (SID) between cmdlets and the SAM backend.
The diagram shows the interaction between the administrative user, the PowerShell cmdlet layer, and the underlying OS security database.
Sources: src/Microsoft.PowerShell.LocalAccounts/LocalAccounts/Commands/NewLocalUserCommand.cs:190-215, test/powershell/Modules/Microsoft.PowerShell.LocalAccounts/Pester.Command.Cmdlets.LocalAccounts.LocalUser.Tests.ps1:400-410
Implementation Details
Module Lifecycle and Loading
The Local Accounts module is considered a core module in the PowerShell ecosystem. On Windows systems, it is typically located within the $PSHOME\Modules path. The module uses updatable help, allowing for culture-specific documentation to be downloaded separately.
Sources: test/powershell/engine/Help/UpdatableHelpSystem.Tests.ps1:11-20, test/powershell/engine/Help/UpdatableHelpSystem.Tests.ps1:105-112
Support for User Objects
Cmdlets in this module return and accept LocalUser objects. This allows for powerful pipeline operations, such as retrieving a user via Get-LocalUser and passing the resulting object directly to Set-LocalUser or Remove-LocalUser.
Sources: test/powershell/Modules/Microsoft.PowerShell.LocalAccounts/Pester.Command.Cmdlets.LocalAccounts.LocalUser.Tests.ps1:560-570, test/powershell/Modules/Microsoft.PowerShell.LocalAccounts/Pester.Command.Cmdlets.LocalAccounts.LocalUser.Tests.ps1:780-790
Summary
Local Accounts Management provides the essential tools for programmatic administration of local Windows accounts. By combining strict validation in the cmdlet layer with direct SAM API interaction in the backend, the system ensures that account management is both user-friendly and secure. The use of strongly typed objects and comprehensive pipeline support enables complex administrative scripts to be written with minimal boilerplate.