windows-users

A native addon for Node.js to query user accounts on Windows platforms

Install

Note to users of pre-C++-2011 compilers only: During the build, the compiler will print many warnings like this:

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

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()

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:
  1. add the offset to the value to get result A
  2. if result A is less than 24, it applies to the given day
  3. 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:
  1. add the offset to the value to get result A
  2. if result A is positive, it applies to the given day
  3. 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