Tcl Windows API extension

This module provides procedures related to management of user and group accounts on Windows operating systems. This documentation is reference material describing related commands. For more introductory material and guide, see the Windows Security chapter in the Tcl on Windows online book.

Standard Options

Most commands allow the following options to be specified:

-system SYSTEMNAME

Several commands, for example, looking up account names or adding users, may be carried out on a target system other than the local system. The -system option allows specification of the target system. This option defaults to the local system if unspecified.

User and Group Accounts

Note that the twapi_base provides some commonly used commands for mapping between account names and SIDs.

The commands new_user and delete_user allow addition and deletion of user accounts. The commands enable_user, disable_user and unlock_user may be used to change the state of a user account. The command get_user_account_info returns various attributes and properties of a user account. These may be modified through the set_user_account_info function or alternatively, modified individually through the following set of functions: set_user_name, set_user_password, set_user_home_dir, set_user_comment, set_user_script_path, set_user_full_name, set_user_country_code, set_user_profile, set_user_home_dir_drive, set_user_expiration.

Information about global and local groups may be retrieved through the get_global_group_info and get_local_group_info commands. New global groups may be created and deleted through the new_global_group and delete_global_group commands. The equivalent commands for local groups are new_local_group and delete_local_group. Users may be added and removed using the commands add_user_to_global_group, add_member_to_local_group, add_members_to_local_group, remove_user_from_global, remove_member_from_local_group and remove_member_from_local_group.

The rights and privileges associated with accounts can be managed through the get_account_rights, find_accounts_with_right, add_account_rights and remove_account_rights commands.

Enumerating Accounts

There are several commands for enumerating users and groups, including group membership.

get_users	Enumerates the locally defined user accounts.
get_global_groups	Enumerates the globally defined groups.
get_local_groups	Enumerates the locally defined groups.
get_local_group_members	Enumerates the members of a local group.
get_global_group_members	Enumerates the members of a global group.
get_user_global_groups	Enumerates the global groups in which a specific user account has membership.
get_user_local_groups	Enumerates the local groups in which a specific user account has direct or indirect membership.

With the exception of get_user_local_groups and get_user_global_groups, all these commands follow the same pattern of invocation and use a standard set of options. Without any optional arguments, the commands return a simple list of user or group names as appropriate. However, the commands also allow retrieval of information with additional detail or in incremental fashion.

To get more detail about about the accounts being returned without making separate calls for each individual account, the -level option may be specified. When this option is specified, the list of accounts returned is a record array with fields that contain the detail values for an item. The argument value passed to the -level option is an integer that indicates the level of detail desired. The valid values for the argument and the specific fields returned in the sublist are dependent on the command and are described in the documentation for the command. See the examples below for sample useage.

On systems (including domains) with a very large number of accounts, it may be better for performance and user responsiveness to retrieve the list in incremental fashion through -resume option. On the initial call to any of the commands, the RESUMEHANDLE value for the option must be specified as 0. The command will then return a list of the form { MOREDATA RESUMEHANDLE COUNT DATA }. In the returned list, MOREDATA is a boolean indicating if there are more accounts to be enumerated. If this value is 1, then the appropriate command can be called again, this time passing RESUMEHANDLE as the value for the -resume option. This process can be repeated as long the MOREDATA field in the returned result is 1. If MOREDATA is 0, there is no more data to be retrieved. The RESUMEHANDLE must be treated as opaque and must not be modified in any way before being passed back in the next call to the command. It is critical that the command be repeated with the correct value of RESUMEHANDLE and only if MOREDATA is 1. The system does not protect against bad values which can crash your application. The other elements returned when the -resume option is used are COUNT and DATA. The former is an estimate of the sum of items returned in this call and those remaining to be returned. Note this is only an estimate and should not be relied on except for rough purposes such as displaying a progress bar. The DATA element is the actual values that are the result of the call. The format of this depends on the use of the -level option. If the -level option was not specified, DATA is a simple list of values (such as user names). If -level was specified to the command, DATA is a record array as described above.

The following sample session demonstrates the use of the two options and the format of the returned data:

(tcl) 63 % get_local_group_members Administrators
Administrator ashok
(tcl) 64 % get_local_group_members Administrators -level 1
-name -comment} {{S-1-5-21-1957994488-1801674531-839522115-500 1 Administrator} {S-1-5-21-1957994488-1801674531-839522115-1003 1 ashok}}
(tcl) 65 % get_local_group_members Administrators -resume 0
0 0 2 {Administrator ashok}
(tcl) 66 % get_local_group_members Administrators -resume 0 -level 1
0 0 4 {{-name -comment} {{S-1-5-21-1957994488-1801674531-839522115-500 1 Administrator} {S-1-5-21-1957994488-1801674531-839522115-1003 1 ashok}}}

Global Account Settings

Certain account settings are applicable across all accounts in a security database, either the local SAM database, or Active Directory in case of domain controllers. The following commands allow for retrieval and modification of these settings.

get_lockout_policy	Returns the policy settings for account lockouts, such as lockout duration.
get_password_policy	Returns the policy settings for account passwords, such as minimum password length.
set_lockout_policy	Modifies the global policy settings for account lockouts.
set_password_policy	Modifies the global policy settings for account passwords.

Commands

add_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?

Adds the privileges and account rights listed in RIGHTS to the account specified by ACCOUNTNAME. The option -system may be used to specify a system as described in Standard Options.

RIGHTS is a list of privileges and account rights. Refer to Authorization constants in the Windows SDK for valid values. Note: you must use the string form of the privilege or right, for example, SeBatchLogonRight, not SE_BATCH_LOGON_NAME.

add_user_to_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?

Adds the user account specified by USERNAME to the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

add_member_to_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME? ?-type name|sid?

Adds the account specified by ACCOUNTNAME to the local group GROUPNAME. ACCOUNTNAME may be either a user name or a global group and may include a domain in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

If the option -type has the value sid, ACCOUNTNAME is treated as an account SID. By default it treated as an account name.

The command does not raise an error if the specified account is already a member of the group.

add_members_to_local_group GROUP ACCOUNTS ?-system SYSTEMNAME? ?-type name|sid?

Adds the account specified in the list ACCOUNTS to the local group GROUPNAME. ACCOUNTS may contain user accounts and global groups and may include a domain in the form domainname\username. Alternatively, ACCOUNTS may be specified as a list of SID's if the option -type has the value sid.

The option -system may be used to specify a system as described in Standard Options.

Unlike the add_member_from_local_group command, this command raises an error without making any changes if any of the specified accounts does not exist or is not a member of the group. The command does not raise an error if the specified account is already a member of the group.

delete_global_group GROUPNAME ?-system SYSTEMNAME?

Deletes a global group GROUPNAME. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

delete_local_group GROUPNAME ?-system SYSTEMNAME?

Deletes a local group GROUPNAME. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

delete_user USERNAME ?-system SYSTEMNAME?

Delete the specified user account. Also, deletes any rights associated with the account in the LSA rights database. The option -system may be used to specify a system as described in Standard Options.

disable_user USERNAME ?-system SYSTEMNAME?

Disables a user account. The option -system may be used to specify a system as described in Standard Options.

enable_user USERNAME ?-system SYSTEMNAME?

Enables a user account. The option -system may be used to specify a system as described in Standard Options.

find_accounts_with_right RIGHT ?-system SYSTEMNAME? ?-name?

Returns a list of all accounts (user and group) that hold the right or privilege specified by RIGHT. The returned list contains the SID's of the account unless the -name option is specified in which case the account names are returned instead.

Refer to Authorization constants in the Windows SDK for valid values for RIGHT. Note: you must use the string form of the privilege or right, for example, SeBatchLogon, not SE_BATCH_LOGON_NAME.

The option -system may be used to specify a system as described in Standard Options.

get_account_rights ACCOUNTNAME ?-system SYSTEMNAME?

Returns the list of rights and privileges for the user or group specified by ACCOUNTNAME. This only includes those directly belonging to the account, and does not include the ones inherited from membership in groups.

The option -system may be used to specify a system as described in Standard Options.

get_global_group_info GROUPNAME ?options?

Retrieves information about the specified global group. The actual information returned depends on the specified options and is returned as a list of the form "option value...". The following options may be specified:

-all	Returns all data items.
-attributes	Returns the group attributes as a list. See get_token_groups_and_attrs for values.
-comment	Returns the comment associated with the group account.
-name	Returns the name of the group.
-sid	Returns the SID for the group.
-members	Returns the members of the group.

get_global_group_members GROUPNAME ?options?

If no options are specified, returns a list of user accounts that are members of the global group GROUPNAME.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields of the returned record array are shown in the following table:

0	-name
1	-name, -attributes

get_global_groups ?options?

If no options are specified, returns the list of global groups on the system.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields in the returned record array are shown in the following table:

0	-name
1	-name -comment,
2	-name -comment, -group_id, -attributes,
3	-name. -comment, -sid, -attributes, This level may not be supported on all versions of Windows.

Refer to the documentation of get_global_group_info for a description of these fields.

get_local_group_info GROUPNAME ?options?

Retrieves information about the specified local group. The actual information returned depends on the specified options and is returned as a list of the form "option value...". The following options may be specified:

-all	Returns all data items.
-comment	Returns the comment associated with the group account.
-name	Returns the name of the group.
-sid	Returns the SID for the group.
-members	Returns the members of the group.

get_local_group_members GROUPNAME ?options?

If no options are specified, returns a list of user accounts that are members of the local group GROUPNAME.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields or the returned record array are shown in the following table:

0	-sid
1	-sid, -sidusage, -name
2	-sid, -sidusage, -domainandname
3	-domainandname

get_local_groups ?options?

If no options are specified, returns the list of local groups on the system.

The following options may be specified to modify the behaviour of the command and the format of the returned data.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields are shown in the following table:

0	-name
1	-comment, -name

Refer to the documentation of get_local_group_info for a description of these fields.

get_lockout_policy ?SYSTEMNAME?

Returns the security database policy for account lockout settings. These may pertain to the SAM database or in the case of domain controllers, Active Directory. SYSTEMNAME is the NetBIOS or DNS name of the system to be queried and defaults to the local system.

The returned value is a dictionary with the following fields:

lockout_duration	Number of seconds that a locked account remains locked.
lockout_observation_window	Maximum time in seconds that can elapse between failed logon events before the account is locked out.
lockout_threshold	Number of logon failures before an account is locked out.

get_password_policy ?SYSTEMNAME?

Returns the security database policy settings for account passwords. These may pertain to the SAM database or in the case of domain controllers, Active Directory. SYSTEMNAME is the NetBIOS or DNS name of the system to be queried and defaults to the local system.

The returned value is a dictionary with the following fields:

force_logoff	Number of seconds before a user is forced to log off. A value of never means the user is never forced to log off.
max_passwd_age	Maximum allowable password age in seconds. A value of none indicates no limit.
min_passwd_age	Minimum allowable time in seconds before a password can be changed.
min_passwd_len	Minimum allowable password length.
password_hist_len	Length of the password history. New passwords must not match any passwords in the password history.

get_user_account_info ACCOUNT ?-system SYSTEMNAME? ?options?

Returns attributes and properties of a user account as a list of the form "option1 value1 ...". ACCOUNT specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed.

The data returned depends on which of the following options are specified:

-acct_expires	Returns the time when the account is set to expire. This value may be never or unknown or the number of seconds since Jan 1, 1970 00:00:00 UTC as accepted by the Tcl clock command.
-all	Returns all data items.
-bad_pw_count	Returns the number of login attempts for that account that failed because of a bad password. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-code_page	Returns an integer corresponding to the code page for the user's preferred language.
-comment	Returns the comment associated with the user account.
-country_code	Returns an integer country/region value for the user's preferred language.
-full_name	Returns the full name of the user.
-global_groups	Returns the global groups of which the account is a member.
-home_dir	Returns the full path to the user's home directory.
-home_dir_drive	Returns the drive letter assigned to the user's home directory.
-internet_identity	Returns the Internet identity of the user. The return value is an empty list if the user is not associated with an Internet identity. Otherwise it is a dictionary with the keys internet_provider_name, internet_principal_name and sid corresponding to the issuer of the identity, the Internet identity and the local SID.
-last_logoff	Returns the time in GMT when the user last logged off. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-last_logon	Returns the time in GMT when the user last logged in. This value may also be never or unknown. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried separately (using the -system option).
-local_groups	Returns the local groups of which the account is a member. This includes only groups of which the account is directly a member and does not include indirect membership through a global group which is itself a member of a local group. See get_user_local_groups for a command that will recursively include groups.
-logon_hours	Returns a bit string of 1's and 0's corresponding to each hour in the week that the user is allowed to log on. Note the week starts based on GMT time, not local time.
-logon_server	Returns the name of the server to which logon requests are sent.
-max_storage	Returns the maximum amount of disk space the user is allowed to use.
-name	Returns the name of the account.
-num_logons	Returns the number of times the user has logged on. In an environment with backup domain controllers, each domain controller maintains this value independently and must be queried (using the -system option) separately. A value of -1 indicates the number is unknown.
-parms	Returns an application specific string.
-password_age	Returns the number of seconds since the password was last changed for the account.
-password_expired	Returns a value of 1 if the account password has expired, and 0 otherwise.
-primary_group_id	Returns the the RID (relative id component of a SID) of the primary global group for the account.
-profile	Returns the full path to the user's profile.
-script_path	Returns the full path to the user's logon script.
-sid	Returns the SID of the user.
-status	Returns one of the values disabled, enabled or locked.
-units_per_week	Returns an integer indicating the number of equal time units into which a week is divided (see -logon_hours).
-usr_comment	Returns the user comment for the account.
-user_id	Returns RID component of the user's SID.
-workstations	Returns a comma-separated list of upto eight workstations from which the user can log in.

get_user_global_groups ACCOUNT ?-system SYSTEMNAME? ?-all? ?-denyonly?

Returns a list of global groups in which the given user account is a member. Without any options, the command will only return those groups which are not marked as intended for deny only purposes. If the -denyonly option is specified, only such groups are returned. If -all is specified (which also overrides -denyonly if present), both types of groups are included in the returned list.

The option -system may be used to specify a system as described in Standard Options.

get_user_local_groups ACCOUNT ?-system SYSTEMNAME? ?-recurse BOOLEAN?

Returns the local groups in which the given user account is a member. If -recurse is not specified or is specified as false, only the local groups of which the account is directly a member are returned. If -recurse is specified as true, the returned list includes local groups of which the account is indirectly a member through its membership in a global group which is a member of the local group. This differs from the -local_groups option of the get_user_account_info command.

The option -system may be used to specify a system as described in Standard Options.

get_users ?-system SYSTEMNAME?

If no options are specified, returns the list of user accounts on the system. Note the returned list includes only accounts defined on the system, not all accounts that are known to the system.

The following options may be specified to modify the behaviour of the command.

-system SYSTEMNAME	See Standard Options.
-level LEVEL	See Enumerating Accounts for how this option changes the format of the returned data. The valid values of LEVEL and the corresponding fields returned are described below.
-resume RESUMEHANDLE	Returns account information in incremental mode. See Enumerating Accounts.

The valid values for LEVEL and the corresponding fields that are returned in the record array are shown in the table below. Note that there may be additional fields returned that are not listed. These should be considered internal and their values not relied on.

0	-name
1	Fields included in level 0 plus -comment, -status, -home_dir, -password, -password_age, -script_path.
2	Fields included in level 1 plus -auth_flags, -full_name, -usr_comment, -parms, -workstations -last_logon, -last_logoff, -acct_expires, -max_storage, -units_per_week, -logon_hours, -bad_pw_count, -num_logons, -logon_server, -country_code, -code_page.
3	Fields included in level 2 plus -user_id, -primary_group_id, -profile, -home_dir_drive, -password_expired.

Refer to get_user_account_info for the meaning of these fields.

new_global_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?

Creates a global group GROUPNAME. The option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

new_local_group GROUPNAME ?-system SYSTEMNAME? ?-comment COMMENT?

Creates a local group GROUPNAME. The option -comment allows a comment to be associated with the group. The option -system may be used to specify a system as described in Standard Options.

new_user USERNAME ?options?

Creates a new user account. The following options may be specified to set the account properties:

-system SYSTEMNAME	Indicates the system on which to create the account.
-comment STRING	Sets the comment associated with the account.
-home_dir PATH	Sets the account's home directory path.
-script_path PATH	Sets the path to the logon script for the account.
-password PASSWORD	Sets the password for the account. PASSWORD should be in encrypted form as returned by by the read_credentials or conceal commands.

remove_member_from_local_group GROUPNAME ACCOUNTNAME ?-system SYSTEMNAME? ?-type name|sid?

Removes the user account or global group specified by ACCOUNTNAME from the local group GROUPNAME. ACCOUNTNAME may be a domain account in the form domainname\username.

The option -system may be used to specify a system as described in Standard Options.

If the option -type has the value sid, ACCOUNTNAME is treated as an account SID. By default it treated as an account name.

The command does not raise an error if the specified account is not a member of the group.

remove_members_from_local_group GROUPNAME ACCOUNTS ?-system SYSTEMNAME? ?-type name|sid?

Removes multiple users or global groups from the local group GROUPNAME. ACCOUNTS is a list of may be a domain accounts in the form domainname\username, or as a list of SID's if the -type option has the value sid.

The option -system may be used to specify a system as described in Standard Options.

Unlike the remove_member_from_local_group command, this command raises an error without making any changes if any of the specified accounts does not exist or is not a member of the group.

remove_account_rights ACCOUNTNAME RIGHTS ?-system SYSTEMNAME?

Removes the privileges and account rights listed in RIGHTS from the account specified by ACCOUNTNAME. The option -system may be used to specify a system as described in Standard Options.

RIGHTS is a list of privileges and account rights. Refer to Authorization constants in the Windows SDK for valid values. Note: you must use the string form of the privilege, for example, SeBatchLogonRight, not SE_BATCH_LOGON_NAME.

remove_user_from_global_group GROUPNAME USERNAME ?-system SYSTEMNAME?

Removes the user account specified by USERNAME from the global group GROUPNAME. The option -system may be used to specify a system as described in Standard Options.

set_lockout_policy DURATION OBSERVEWINDOW THRESHOLD ?SYSTEMNAME?

Sets the security database policy account lockout settings. These may pertain to the SAM database or in the case of domain controllers, Active Directory. SYSTEMNAME is the NetBIOS or DNS name of the system to be queried and defaults to the local system. DURATION, OBSERVEWINDOW and THRESHOLD correspond to the lockout_duration, lockout_observation_window and lockout_threshold values returned by get_lockout_policy.

set_password_policy SETTING VALUE ?SYSTEMNAME?

Sets the security database policy settings for account passwords. These may pertain to the SAM database or in the case of domain controllers, Active Directory. SYSTEMNAME is the NetBIOS or DNS name of the system to be queried and defaults to the local system.

SETTING is the name of a setting as returned by get_password_policy and VALUE is the value to be assigned to it.

set_user_account_info account ?-system SYSTEMNAME? ?options?

Sets attributes and properties of a user account. account specifies the user account for which the information is to be retrieved. The option -system may be used to specify the system from whose context the account lookup should be performed. The following options may be specified to set various properties of the account:

-comment STRING	Sets the comment associated with the account.
-full_name STRING	Sets the full name of the user.
-country_code INTEGER	Sets the country code associated with the user account.
-home_dir PATH	Sets the account's home directory path.
-home_dir_drive	Sets the account's home directory drive.
-acct_expires DATETIME	Sets the time at which the account will expire. See set_user_expiration for valid formats for DATETIME.
-name STRING	Sets the name field containing the name of the account.
-script_path PATH	Sets the path to the logon script for the account.
-profile PATH	Sets the path to the account's profile.

set_user_comment USERNAME STRING ?-system SYSTEMNAME?

Sets the comment associated with the specified user account to STRING The option -system may be used to specify a system as described in Standard Options.

set_user_country_code USERNAME INTEGER ?-system SYSTEMNAME?

Sets the country code for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_expiration USERNAME DATETIME ?-system SYSTEMNAME?

Sets the time at which the specified user account expires. DATETIME may be specified as the number of seconds since Jan 1, 1970 00:00:00 UTC, the string never, or in any format accepted by the clock scan command. This last option is only for backward compatibility and is deprecated as it may lead to ambiguity. The option -system may be used to specify a system as described in Standard Options.

set_user_full_name USERNAME STRING ?-system SYSTEMNAME?

Sets the full name for the specified user to STRING. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir USERNAME PATH ?-system SYSTEMNAME?

Sets the home directory for the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_home_dir_drive USERNAME DRIVEPATH ?-system SYSTEMNAME?

Sets the home directory drive for the specified user account. The option -system may be used to specify a system as described in Standard Options.

set_user_name USERNAME NEWNAME ?-system SYSTEMNAME?

Modifies the name of the specified user account to NEWNAME. The option -system may be used to specify a system as described in Standard Options.

set_user_password USERNAME PASSWORD ?-system SYSTEMNAME?

Sets the password of the specified user account to PASSWORD. PASSWORD but should be in encrypted form as returned by by the read_credentials or conceal commands. The option -system may be used to specify a system as described in Standard Options.

set_user_profile USERNAME PATH ?-system SYSTEMNAME?

Sets the location of the profile of the specified user account to PATH. The option -system may be used to specify a system as described in Standard Options.

set_user_script_path USERNAME PATH ?-system SYSTEMNAME?

Sets the path to the login script for the specified user account. The option -system may be used to specify a system as described in Standard Options.

unlock_user USERNAME ?-system SYSTEMNAME?

Unlocks a user account that has been locked out. The option -system may be used to specify a system as described in Standard Options.

Users and Groups

SYNOPSIS

DESCRIPTION

Standard Options

User and Group Accounts

Enumerating Accounts

Global Account Settings

Commands

COPYRIGHT

TWAPI 4.3.5 Documentation