windows-users
A native addon for Node.js to query user accounts on Windows platforms
Install
C:\Users\myUser>npm install windows-users
Note to users of pre-C++-2011 compilers only: During the build, the compiler will print many
warnings like this:
..\src\deepinfo.cc(63): warning C4482: nonstandard extension used: enum 'UserField' used in qualified name
These can be safely ignored.
Usage
var users = require('windows-users')
var nameList = users.list()
console.log('The user accounts on this system are:', nameList.join(', '))
nameList.forEach(function(username) {
var account = users.getDetails(username)
if (account.accountType === 'administrator' && !account.disabled) {
}
})
var infoList = users.list({detailed: true})
for (var i = 0; i < infoList.length; i++) {
var account = infoList[i]
if (account.disabled || account.lockedOut) continue
var fullInfo = users.getDetails(account.name)
console.log('Account %s has SID: %s', fullInfo.name, fullInfo.sid)
if (fullInfo.lastLogon > 0)
console.log('Last logon was', new Date(fullInfo.lastLogon * 1000))
var localGrps = users.getLocalGroups(account.name)
var globalGrps = users.getGlobalGroups(account.name)
}
For each of the four available functions, the user may expect the result of
querying the localhost as the synchronous return value if no callback function
is added to the argument list. Simply supply a callback function as the last
argument to turn the call asynchronous.
A callback function is required if a host other than the localhost is to be
queried.
Note: In some environments, the synchronous functions may throw an Error
of
"access is denied to current user"
, and any of the asynchronous functions may
pass this error to the callback. This would be a consequence of the user's
permissions versus the particular security configuration of the domain.
API
users.list([options])
Synchronous. Returns a list of all user accounts known to the local system,
optionally according to the specified options.
-
options
{Object} Optional.
-
detailed
{Boolean} A flag to request additional fields of data with each
account name. The default is to return account names only.
See Enumeration Fields table below.
Note that the additional fields included by giving this option are not
exhaustive; for that, see users.getDetails()
with the
fullDetails
option.
-
filter
{Number} A bit-field specifying the types of user accounts to
include (See User Account Type Constants below). This
field can be made to specify multiple types by combining them with logical OR
(|
) notation. The default is to request all types; a value of 0
will also
get this result, as will a combination of all the constants.
-
Return: {Array} array of {String | Object}
If no options
are given, this will be an array of the names of every user
account known to the system, including special account types if any.
If option detailed
is set true
, it will be an array of objects containing
all of the fields in the Enumeration Fields table
below.
If option filter
is given and set non-zero, the array will include only
the accounts with type(s) matching the specified value(s).
users.list([options,] [hostname,] callback)
Asynchronous. Passes a list of all user accounts known to the local system
(or on the system named by hostname
instead) to the callback
function.
The contents of the list depends on whether and which options are given, as
described above for the synchronous version.
If hostname
is given and it is unknown or cannot be accessed, an Error
is
passed back.
options
{Object} Optional. As described for synchronous version.hostname
{String} Optional.
The name of a host in the domain to query. An empty value (undefined
, null
,
or empty string) may be passed to get the same effect as omitting this argument.callback
{Function}
- error {Error |
null
} - data {Array} as described for return value of synchronous version,
if no error.
users.getDetails(username [, fullDetails])
Synchronous. Returns information about the named user account if it is known
on the local system; otherwise an Error
is thrown.
username
{String} Logon name of user account.fullDetails
{Boolean} Optional. Pass true
to request all available details.- Return: {Object} A user account record containing all of the fields listed in
the Enumeration Fields table; if a
true
value was
passed for the fullDetails
parameter, the record will also contain the fields
listed in the Additional Fields table.
users.getDetails(username [, fullDetails] [, hostname], callback)
Asynchronous. Passes the account information for the named user (optionally
on the system named by hostname
) to the callback
function, if the username
is known; otherwise an Error
is passed to the callback. If hostname
is
given and it is unknown or cannot be accessed, an Error
is passed back.
username
{String} Logon name of user account.fullDetails
{Boolean} Optional. Pass true
to request all available details.hostname
{String} Optional.
The name of a host in the domain to query. An empty value (undefined
, null
,
or empty string) may be passed to get the same effect as omitting this argument.callback
{Function}
- error {Error |
null
} - data {Object} as described for return value of synchronous version,
if no error.
users.getGlobalGroups(username)
Synchronous. Returns the list of global groups to which the named user account
belongs, if the username
is known on the local system; otherwise an Error
is
thrown.
username
{String} Logon name of user account.- Return: {Array} array of global group names as strings
users.getGlobalGroups(username [, hostname], callback)
Asynchronous. Retrieves the list of global groups to which the named user
account belongs (optionally on the system named by hostname
) and passes it to
the callback
function, if the username is known to the host; otherwise an
Error
is passed to the callback. If hostname
is given and it is unknown or
cannot be accessed, an Error
is passed back.
username
{String} Logon name of user account.hostname
{String} Optional.
The name of a host in the domain to query. An empty value (undefined
, null
,
or empty string) may be passed to get the same effect as omitting this argument.callback
{Function}
- error {Error |
null
} - data {Array} as described for return value of synchronous version,
if no error.
users.getLocalGroups(username)
Synchronous. Returns the list of local groups to which the named user account
belongs, if the username
is known on the local system; otherwise an Error
is
thrown.
username
{String} Logon name of user account.- Return: {Array} array of local group names as strings
users.getLocalGroups(username [, hostname], callback)
Asynchronous. Retrieves the list of local groups to which the named user
account belongs (optionally on the system named by hostname
) and passes it to
the callback
function, if the username is known to the host; otherwise an
Error
is passed to the callback. If hostname
is given and it is unknown or
cannot be accessed, an Error
is passed back.
username
{String} Logon name of user account.hostname
{String} Optional.
The name of a host in the domain to query. An empty value (undefined
, null
,
or empty string) may be passed to get the same effect as omitting this argument.callback
{Function}
- error {Error |
null
} - data {Array} as described for return value of synchronous version,
if no error.
User Account Type Constants
users.constants.NORMAL
- Default account type, representing a typical user.
The corresponding string value returned for the accountType
field is "normal"
.users.constants.TEMP_DUPLICATE
- Account type for users whose primary
account is in another domain. The corresponding accountType
field value is
"temp duplicate"
.users.constants.INTERDOMAIN_TRUST
- A Permit To Trust account for a domain
that trusts other domains. The corresponding accountType
field value is
"interdomain trust"
.users.constants.WORKSTATION_TRUST
- A computer account for a computer that
is a member of this domain. The corresponding accountType
field value is
"workstation trust"
users.constants.SERVER_TRUST
- A computer account for a backup domain
controller that is a member of this domain. The corresponding accountType
field value is "server trust"
.
Enumeration Fields
Field Name | Type | Description |
---|
name | String | The username for account logon. |
fullName | String | Alternate identification of user; may be an empty string. |
comment | String | Descriptive comment; may be an empty string. |
accountType | String | Account usage type. See notes for User Account Type Constants. |
disabled | Boolean | The user's account is disabled. |
lockedOut | Boolean | The account is currently locked out. |
passwdRequired | Boolean | The user must use a password to log on. |
passwdCanChange | Boolean | The user can change the password. |
passwdExpired | Boolean | The user's password has expired. |
passwdNeverExpires | Boolean | Currently set for password never to expire. |
encryptedPasswdOK | Boolean | Password is stored under reversible encryption in the Active Directory. |
smartcardRequired | Boolean | The user must log on with a smart card. |
useOnlyDES | Boolean | Restricted to use only DES encryption types for keys. |
noPreauthRequired | Boolean | No Kerberos preauthentication required for logon. |
notDelegated | Boolean | Other users cannot act as delegates of this account. |
trustedForDeleg | Boolean | The account is enabled for delegation. |
trustedToAuthDeleg | Boolean | The account is trusted to authenticate a user outside of the Kerberos security package and delegate that user through constrained delegation. |
For more information about the Boolean
fields above, see the table of
corresponding flags under the description of the usri20_flags field on
this page at MSDN.microsoft.com.
Additional Fields Available through getDetails()
Field Name | Type | Description |
---|
sid | String | The unique security identifier (SID) of the user. |
primaryGroupId | Number | The relative identifier (RID) of the Primary Global Group for the user. Information about RIDs can be found on the MSDN page about SID Components. |
homeDir | String | Path of the user's home directory; may be an empty string. |
homeDirDrive | String | The letter of the drive where the user's home directory resides; may be an empty string if homeDir is empty. |
profilePath | String | Path of the user's profile; can be an empty string, a local absolute path, or a UNC path. |
scriptPath | String | Path of the user's logon script file; may be an empty string. |
maxStorage | Number | If not null , the maximum disk space the user can use, in bytes. A null value means "unlimited". |
privilegeLevel | String | "guest" , "user" , or "administrator" (see MSDN page about Privileges). |
isAccountsOperator | Boolean | Flag: the user has Accounts Operator privilege. |
isServerOperator | Boolean | Flag: the user has Print Operator privilege. |
isPrintOperator | Boolean | Flag: the user has Server Operator privilege. |
userComment | String | Another comment associated with the user; may be an empty string. |
countryCode | Number | The country/region code for the user's language of choice. |
codePage | Number | The code page for the user's language of choice. |
appParams | String | Reserved for use by some applications; may be an empty string. |
passwdAge | Number | Number of seconds passed since password was last changed. The value 0 means "never". |
accountExpires | Number | If not null , the time when the account expires, in number of seconds after UNIX epoch. A null value means "never". |
logonHours | Array | If not null , a 2-dimensional array identifying GMT hours of the week during which the user can log on. The outer array has an element for each day of the week, starting with Sunday; each element is an array of integers representing 0-indexed hours of the day, GMT (see "How To" below). A null value means no restriction. |
workstations | String | Comma-delimited list of workstations from which the user can log on; may be an empty string, meaning: unrestricted. |
logonServer | String | Name of the server to which logon requests are sent. The value "\\\\*" means any logon server can handle requests. An empty string means the domain controller handles requests. |
lastLogon | Number | Time of last logon, in number of seconds after UNIX epoch; the value 0 means "never". About accuracy, see special notes for corresponding field usri4_last_logon on this page at MSDN.microsoft.com. |
logonCount | Number | If not null , the number of times logon to this account was successful. A null value means "unknown". About accuracy, see special notes for corresponding field usri4_num_logons on this page at MSDN.microsoft.com. |
badPasswdCount | Number | If not null , the number of times logon was attempted with an incorrect password. A null value means "unknown". About accuracy, see special notes for corresponding field usri4_bad_pw_count on this page at MSDN.microsoft.com. |
Logon Hours: How To...
As noted above, the values in the logonHours
structure are according to
Greenwich Mean Time (GMT). You will probably want to convert to values relative
to your local timezone.
- If your timezone offset is positive:
- add the offset to the value to get result A
- if result A is less than 24, it applies to the given day
- else take the modulus (result A % 24) and apply it to the following day.
Note that if the day index is 6, the following day would be Sunday (index 0).
- If your timezone offset is negative:
- add the offset to the value to get result A
- if result A is positive, it applies to the given day
- else add (result A + 24) and apply it to the previous day.
Note that if the day index is 0, the previous day would be Saturday (index 6).
License: MIT