
Scott Field (sfield)	10-Jun-96 (v2.0)
Scott Field (sfield)	10-Nov-95 (v1.0)

Overview
--------

This document describes SU.EXE, a utility included with the Windows NT Resource Kit.

SU provides the ability to start a process running as an arbitrary user.  The utility is named after the SU utility for the UNIX family of operating systems.

The new process will run in the security context of the specified user, providing that the specified username, domain, and password are correct.  To start a process as an arbitrary user, you must have the password for the corresponding user.

The new process will start with an environment block representing the per-user environment variables that Windows NT maintains.  This behavior can be disabled.

When the new process starts, the Registry hive representing the target user will be available in the process.  This portion of the Registry is accessed through the HKEY_CURRENT_USER Registry key.  This behavior can also be disabled.

The caller of this application needs the following privileges:

SeTcbPrivilege "Act as part of the operating system"
SeIncreateQuotaPrivilege "Increase Quotas"
SeAssignPrimaryTokenPrivilege "Replace a process level token"
SeRestorePrivilege "Restore files and directories"
 (only required for user Registry hive preparation)

By default, only the Local System account has the SeTcbPrivilege and SeAssignPrimaryTokenPrivilege.  For this reason, you will need to grant the above privileges to the user accounts/groups which are authorized to execute SU.  These privileges can be granted via the User Manager tool, option Policies | User Rights | click "Show Advanced User Rights". Privileges granted in this manner will take affect when the user which was the target of the privilege operation logs on.

The logon type equates to the required logon right which the target user needs.  Furthermore, the logon type dictates how the access token representing the target user is populated.  The Sid with type SE_GROUP_LOGON_ID in the access token for the new process will represent the type of logon (Batch, Interactive, Service). Logon rights can be granted via User Manager in the same manner mentioned above.


Usage details
-------------

Usage: su <User> "[cmdline]" [domain] [[Winsta\]Desktop] [options]
  -cb do not create new console	(do not use with redirected passwords)
  -e disables environment preparation (Inherit parent environment)
  -l disables loading of the user Registry hive (use .Default)
  -v verbose output to STDOUT
  -w do not wait on child (Registry hive will remain loaded)

One of the following logon types may be specified.  Default is interactive.
  -b batch, target user needs SeBatchLogonRight
  -i interactive, target user needs SeInteractiveLogonRight
  -s service, target user needs SeServiceLogonRight
  -n network, target user needs SeNetworkLogonRight (WinNT 4.0 only)

Not specifying a cmdline invokes the default command processor (%comspec%)
Not specifying a domain causes account lookup in the following order:
  Well-known, built-in, local accounts, primary domain, trusted domains.
Specifying "." as the domain limits the LogonUser search to the local machine.
Not specifying Winsta\Desktop launches child on current Winsta\Desktop.
Winsta0\Default is the user default interactive Windowstation and desktop.


The first non-switch argument is the username for the new process.
This is the only required argument.

The second non-switch argument is the command line to execute as the target user.
This argument is optional, and can be NULL to cause the default command processor specified in the environment variable %comspec% to be executed.

The third non-switch argument is the domain name for the target user.
This argument is optional, and can be NULL to cause default domain name lookup.  In this case the domain lookup occurs in the following order, until the domain for the target user is found:
  Well-known, built-in, local accounts, primary domain, trusted domains
This argument can be set to "." to indicate that the account lookup	is to be limited to the local machine.

The fourth non-switch argument is the target windowstation and desktop for the new process.
This argument is optional.  Not specifying this parameter causes the new process to run on the same windowstation and desktop su was launched from.  Furthermore, when providing this argument, only the desktop name is required.
Not specifying a windowstation name causes the process to run on the current windowstation in the supplied desktop.  When specifying a windowstation, the windowstation and desktop pair must be delimited as follows:  "windowstationname\desktopname"; otherwise, "desktopname" is sufficient.

Switches can be specified in any order, anywhere on the command line.  All switches are optional.

-cb do not create new console
If the new process is a console process, it will inherit the console of the caller.
This flag should not be combined with -w when starting console applications.  Furthermore, the password should not be supplied when redirecting passwords when starting console applications.

-dn don't switch to new desktop
If the new process is set to run on a desktop which differs from the current desktop, do not switch to the new desktop.
The default is to switch to the new desktop which makes the new desktop active and brings it to the foreground.
Note that SU will not return until the new process exits unless the -w switch is specified.

-e disables environment preparation (Inherit parent environment)
Do not prepare the user environment for the new process.  Inherit the environment from SU.

-l disables loading of the user Registry hive (use .Default)
Do not load the user Registry hive for the target user.
If the hive happens to be loaded for the target user, the new process will behave the same way with HKEY_CURRENT_USER which it would if -l was not specified.  If -l is specified without -e, a user default environment will be created for the new process, versus creating a user specific environment for the new process.

-v verbose output to STDOUT
Display details related to the creation of the new process.

-w do not wait on child (Registry hive will remain loaded)
SU will not wait for the new process to exit before returning to the caller.
This means that SU cannot unload the user Registry hive for the target user if one was loaded on behalf of that user.  This flag should not be combined with the -cb flag when starting a console based application, otherwise, console output will be intermixed.

-b batch, target user needs SeBatchLogonRight Batch logon type.
The target user must possess the SeBatchLogonRight.
This logon type is not utilized by Microsoft and is available for use in custom applications.

-i interactive, target user needs SeInteractiveLogonRight Interactive logon type.
The target user must possess the SeInteractiveLogonRight.
This logon type is the same logon type which occurs when a user physically logs onto a Windows NT machine.

-s service, target user needs SeServiceLogonRight Service logon type.
The target user must possess the SeServiceLogonRight.
The logon type is for service style logons performed by the service control manager.

-n network, target user needs SeNetworkLogonRight (Network logon type).
The target user must possess the SeNetworkLogonRight.
The logon type is for network style logons, such as impersonation over named-pipes, connection over shares, etc.
Useful for testing network user access to resources on the local machine.
Only supported under Windows NT 4.0

Environment variable options
----------------------------

SU_USERNAME
SU_PASSWORD
SU_DOMAIN
SU_COMMANDLINE
SU_DESKTOP

Graphical user interface
------------------------


Example command lines
---------------------

Default assumptions are as follows:

If no command line is specified, execute the command line specified by the %comspec% environment variable.

If no domain is specified, use default account search logic.

If no winsta\desktop is specified, the new process will run on the same windowstation and desktop that was used to launch SU.

The new process will have an environment block similar to that generated for a standard interactive logon.  This feature is disabled via the -e switch.

The new process will have the user Registry hive loaded, if available.  This behavior is disabled via the -l switch.

The logon type will be Interactive, which requires the target user have the SeInteractiveLogonRight.  The logon type can be changed to batch or service, via the -b and -s switches.

Command lines:

su administrator
Start the default command line in security context of the first account found with name Administrator.

su administrator eventvwr.exe .
Start EVENTVWR.EXE as the Administrator.  Only search the local account database for user Administrator.

su scott -v -b
Start the default command line in the first account found with name scott.  Display verbose output related to the creation of the new process.  The logon type will be Batch, which requires that user scott has the SeBatchLogonRight.

su scott "" bristol -cb
Start the default command line in the account scott in domain bristol.  Do not create a console window for the new process (use the current console).

su scott "windbg.exe pview.exe" bristol -e -l
Start command line WINDBG.EXE PVIEW.EXE.  The new process will run in the account scott in domain bristol.  The user environment will not be prepared for the new process; the environment will be inherited from the SU process.  Do not load the user Registry hive for user scott.

su scott cmd.exe "" winsta0\default -w
Start CMD.EXE in the first account found with name scott.  The new process will run on the windowstation named "winsta0" and desktop named "default, which is the user default interactive windowstation and desktop.  This would be useful if executed from a non-interactive service running in the Local System account.  Do not wait on the new process to exit before returning from SU.

su scott cmd.exe bristol winsta0\mydesktop
Start CMD.EXE on a windowstation and desktop named winsta0\mydesktop, and switch to desktop.

Avoiding password prompting
---------------------------

It is possible to redirect a password to avoid prompting, providing that STDIN is redirected accordingly.  If su were running under a command processor, the following approaches would be suitable for redirecting a password.

su scott < c:\password\scott.txt
Password for user scott is obtained from C:\PASSWORD\SCOTT.TXT.  The password must be followed by a carriage return in file C:\PASSWORD\SCOTT.TXT.  On NTFS file systems, it would be suitable to apply security to c:\password\scott.txt such that only the caller(s) of the su utility has access to the password file or directory.

echo mypassword | su scott
Password "mypassword" for user scott is piped to su.  This approach is useful for batch files.  Note that on NTFS file systems, the batch file executing this command should have security applied such that only the caller(s) of the su utility have access to the batch file.	Note that some command processors may not handle this case properly.

In addition, it is possible to avoid password prompting by setting the environment variable SU_PASSWORD in the process or batch file that launches SU.  This environment variable is only used when the SU Graphical User Interface is NOT invoked.


Usage under the Windows NT scheduler
------------------------------------

This utility can be utilized under the Windows NT scheduler service, to allow scheduling of jobs in various user contexts.

Note that when the scheduler service runs in the Local System account, it will have all required privileges to execute SU.  If the scheduler service is running in a user account, this account must be configured such that all of the required privileges mentioned earlier are present in the users account.

If the scheduler service does not run in the Local System account, it is not possible to start a process on the "winsta0\default" windowstation and desktop.  Therefore, it is not possible to start a process that is visible on the user default desktop in this manner.

If you need to run scheduled SU jobs that are visible on the user default desktop, run the scheduler service in the Local System account.

Example scheduler command line follows:

at 10:30
 "cmd.exe /c su.exe scott pview.exe england winsta0\default < c:\scott.txt"

At 10:30AM, start PVIEW.EXE in the user account england\scott, on the user default desktop "winsta0\default", obtaining the user password from the file C:\SCOTT.TXT.

In this case, CMD.EXE /C is used to start su.exe, which enabled CMD.EXE to redirect input to SU.EXE from C:\SCOTT.TXT.  Note that the "/c" switch for CMD.EXE causes CMD.EXE to exit when SU.EXE returns, thus ending the process.

at 1:30
 "cmd.exe /c su.exe guest cmd.exe . winsta0\winlogon < c:\guest.txt"
At 1:30AM, start CMD.EXE in the local user account guest, on the desktop "winsta0\winlogon", obtaining the user password from the file C:\GUEST.TXT.  The winlogon desktop is the desktop used during an interactive logon.  This example provides a means for starting a process on this desktop; however, this is not recommended.

Furthermore, the new SU environment string options can be used in conjunction with batch files executed under the Windows NT scheduler.

The following batch file would execute msmail32.exe in the user account named Scott in domain England, with password FooBar:

set SU_COMMANDLINE=msmail32.exe
set SU_DOMAIN=England
set SU_PASSWORD=FooBar
su.exe Scott

Limitations
-----------

1) Environment variables contained in AUTOEXEC.BAT are not yet populated to the environment of the new process.
2) Environment variables HOMEDRIVE and HOMEPATH are not yet populated to the environment of the new process.
3) Mandatory profiles are not supported.  Furthermore, if a profile does not exist for the target user, a default profile is not prepared; Registry operations against HKEY_CURRENT_USER will not be persistent.
4) Network drives are not connected for the target process.  Windows NT makes drive letter mappings global, which could cause collisions when multiple users are logged on; for this reason, network drives are not reconnected.
