Crate windows_users

Expand description

Windows Users

A Rust crate for managing local Windows users and groups using the Windows API in Rust.

§Features

Create, update, delete, and fetch local users
Create, update, delete, and query local groups
Add or remove users from local groups
Support for local and remote machine management
Well-known SID helpers (Users, Administrators, etc.)
User enumeration with UserFilterFlags

§Installation

Add this to your Cargo.toml:

[target.'cfg(windows)'.dependencies]
windows_users = "0.1.0"

§Usage Examples

§Create a manager

use windows_users::UserManager;

// Local machine
let mgr = UserManager::local();

// Remote machine
let mgr = UserManager::remote(r"\\SERVER01");

§Creating a User and Assigning a Group

On Windows, creating a local user account is often not enough by itself.
A user should usually be added to a local group so Windows can determine which permissions and capabilities the account has.

The most common groups are:

Users → standard account with basic access to the machine
Administrators → elevated account with full system privileges

In most applications, adding the account to the Users group is the recommended and safest default.

use windows_users::{UserManager, User, well_known_sid};

let mgr = UserManager::local();

let username = "DemoUser1";

// Create the user
let user = User::builder()
    .name(username)
    .password("P@ssw0rd123!")
    .full_name("Demo User")
    .comment("User created with group assignment")
    .build();

match mgr.add_user(&user) {
    Ok(_) => println!("User created"),
    Err(e) => {
        eprintln!("Failed to create user: {e}");
        return;
    }
}

// Add the user to the standard Users group
let users_group = well_known_sid::USERS.name(&mgr).unwrap();

match mgr.add_users_to_group(&[username], &users_group) {
    Ok(_) => println!("User added to Users group"),
    Err(e) => eprintln!("Failed to add user to group: {e}"),
}

// Delete the user
match mgr.delete_user(username) {
    Ok(_) => println!("User deleted"),
    Err(e) => eprintln!("Failed to delete user: {e}"),
}

§Creating and Managing a User

use windows_users::{UserManager, User, UserUpdate};

let mgr = UserManager::local();

let username = "DemoUser2";

// Create a new user
let user = User::builder()
    .name(username)
    .password("P@ssw0rd123!")
    .full_name("Demo User")
    .comment("Created from windows_users")
    .build();

// Add the user
match mgr.add_user(&user) {
    Ok(_) => println!("User created"),
    Err(e) => eprintln!("Failed to create user: {e}"),
}

// Verify the user exists
match mgr.user_exists(username) {
    true => println!("User exists"),
    false => eprintln!("User does not exist or check failed"),
}

let settings = UserUpdate::builder()
    .comment("Updated comment")
    .full_name("Demo User Updated")
    .build();

// Update the user
match mgr.update_user(username, &settings) {
    Ok(_) => println!("User updated"),
    Err(e) => eprintln!("Failed to update user: {e}"),
}

// Delete the user
match mgr.delete_user(username) {
    Ok(_) => println!("User deleted"),
    Err(e) => eprintln!("Failed to delete user: {e}"),
}

§Using Struct Methods

use windows_users::{UserManager, User, UserUpdate};

let mgr = UserManager::local();

// Create a new user
let mut user = User::builder()
    .name("DemoUserMethods")
    .password("P@ssw0rd123!")
    .build();

// Add the user
match user.add(&mgr) {
    Ok(_) => println!("User created"),
    Err(e) => eprintln!("Failed to create user: {e}"),
}

// Verify the user exists
match user.exists(&mgr) {
    true => println!("User exists"),
    false => eprintln!("User does not exist or check failed"),
};

let update = UserUpdate::builder()
    .comment("Updated via struct method")
    .build();

// Update the user
match user.update(&mgr, &update) {
    Ok(_) => println!("User updated"),
    Err(e) => eprintln!("Failed to update user: {e}"),
}

// Delete the user
match user.delete(&mgr) {
    Ok(_) => println!("User deleted"),
    Err(e) => eprintln!("Failed to delete user: {e}"),
}

§Managing Group Membership

use windows_users::{UserManager, well_known_sid} ;

let mgr = UserManager::local();

let username = ["DemoUser"];
let group_name = well_known_sid::USERS.name(&mgr).unwrap();

match mgr.add_users_to_group(&username, &group_name) {
    Ok(_) => println!("User added to group"),
    Err(e) => eprintln!("Failed to add user to group: {e}"),
}

match mgr.list_group_members(&group_name) {
    Ok(members) => {
        for member in members {
            println!("{}\\{}", member.domain(), member.name());
        }
    }
    Err(e) => eprintln!("Failed to list members: {e}"),
}

match mgr.remove_users_from_group(&username, &group_name) {
    Ok(_) => println!("User removed from group"),
    Err(e) => eprintln!("Failed to remove user from group: {e}"),
}

§Listing Local Users

use windows_users::{UserFilterFlags, UserManager};

let mgr = UserManager::local();

match mgr.count_users(UserFilterFlags::NORMAL_ACCOUNT) {
    Ok(count) => println!("Normal accounts: {count}"),
    Err(e) => eprintln!("Failed to count users: {e}"),
}

match mgr.list_users(UserFilterFlags::NORMAL_ACCOUNT) {
    Ok(users) => {
        for user in users {
            println!("User: {}", user.name());
        }
    }
    Err(e) => eprintln!("Failed to list users: {e}"),
}

§Requirements

Windows 7 or later
Administrative privileges for certain operations

§Support

For issues and questions:

Open an issue on GitHub
Check the documentation

§License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Modules§

well_known_sid: https://learn.microsoft.com/en-us/windows/win32/secauthz/well-known-sids

Structs§

Group: Representation of a Windows local group.
GroupMember: Representation of a member of a Windows local group.
LogonHours: Represents the logon hours for a user, allowing you to specify which hours of the week a user is allowed to log on.
Sid: A Windows Security Identifier (SID).
User: Represents detailed information about a Windows user account. Rust-native version of USER_INFO_3, with appropriate types and semantics.
UserAccountFlags: User account flags from usri3_flags
UserAuthFlags: Operator privileges flags from usri3_auth_flags
UserFilterFlags: Flags used for NetUserEnum filter parameter
UserManager: Provides an interface to manage Windows user accounts on either the local machine or a remote server.
UserUpdate: Struct for updating Windows user accounts.

Enums§

SidType: SID name usage types (SID_NAME_USE)
UserPrivilege: User privilege levels from usri3_priv
WindowsUsersError: Deriving common traits to automatically implement error handling functionality.