win.elevate.ElevationToolkit.htm Maven / Gradle / Ivy
Elevation Toolkit (Elevate and IsElevated)
Elevation Toolkit (Elevate and IsElevated)
Copyright © 2010 by Bill Stewart
Freeware License
These programs may be used freely in any environment without payment to the author, with the following conditions:
- Give me credit.
- Let me know how you're using the programs.
- The programs and this documentation must not be modified.
- The programs cannot be used as a part another software package without notifying the author.
These programs are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Background
Starting in Windows Vista and later, Microsoft introduced a new technology into the Windows operating system called User Account Control (UAC). The purpose of UAC is to make it easier for programmers to develop software to run with limited user accounts (LUA), and to make it easier for end users to log on with a limited account as well. One of UAC's behaviors is to disable the Administrators group token when logging on using an administrative account. In other words, when UAC is enabled, logging on as an administrator has the same effect as logging on with a limited account. You are still a member of the Administrators group, but your administrative privileges are disabled.
When you attempt to perform an administrative task that a limited account cannot perform, Windows will request elevation. If you are a member of the Administrators group, Windows will prompt you for permission to continue. If you grant permission, Windows will run the program you specify, but with the Administrators group token enabled. If you are not a member of Administrators, Windows will prompt for administrative credentials. If you enter valid administrative credentials, Windows will run the specified program with the administrative credentials you specify. A program running with full administrative credentials is said to be running elevated. Prior to UAC, logging on as a member of Administrators meant that all processes you started ran elevated. (This is also the case if you disable UAC, which is not recommended.)
Windows provides a way to run an arbitrary program elevated by right-clicking on the program and then choosing the Run as administrator option. However, there is currently no command-line equivalent for requesting program elevation. This is the purpose of the Elevate program (Elevate32.exe and Elevate64.exe). The Elevate program requests elevation for a program that you type on its command line.
Savvy readers already know that Aaron Margosis provided an Elevate.js script on his Non-admin blog, but Elevate32.exe (and Elevate64.exe) has one distinct advantage: It can wait for the program to complete and return its exit code. This is useful in scripts where you want to run a program elevated and wait for it to complete. It can also specify the program's initial window state (e.g., minimized or hidden), which may be useful in some cases.
The IsElevated program (IsElevated32.exe and IsElevated64.exe) tests whether the current program is elevated and returns an exit code of 0 if the program is not elevated, or 1 if the program is running elevated. Scripts can use IsElevated to check for elevation before performing tasks that require elevation.
Using Elevate
Use Elevate32.exe on 32-bit Windows platforms and Elevate64.exe on 64-bit Windows platforms. Elevate32.exe runs on x64 Windows, but keep in mind that it runs in the SysWOW64 compatibility subsystem.
Elevate32 [-s n] [-d dir] [-w] [-q] -- program [parameters [...]]
Important! All command-line arguments must appear before the program name on the command line.
- -s
- Specifies the program's initial window state. See the table below for possible numeric values.
- -d
- Specifies the program's starting directory. Note that this argument is ignored on Windows Vista and newer as a security measure; it only works on Windows XP and earlier. The default is to start the program in its own directory.
- -w
- Waits for the program to complete, and then exits with the program's exit code.
- -q
- Runs quietly (no error messages).
- --
- Ends command-line argument processing; i.e., the first argument after the -- is the command line to run.
- program [parameters [...]]
- The command line to elevate.
If you use the -w argument, Elevate will wait for the program to complete and exit with the program's exit code. If you cancel the elevation prompt, Elevate will return an exit code of 1223 (ERROR_CANCELLED).
Elevate works on Windows 2000 and later, but if you use it on Windows versions earlier than Vista, it will display the "Run as" dialog instead. If you use it on Windows Vista or later with UAC disabled (not recommended), Elevate will simply run the program and it will not prompt for confirmation or credentials.
Table: Valid Window State Values
Value
Windows API Constant*
Description
0
SW_HIDE
Hides the window and activates another window.
1
SW_SHOWNORMAL
Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
2
SW_SHOWMINIMIZED
Activates the window and displays it as a minimized window.
3
SW_SHOWMAXIMIZED
Activates the window and displays it as a maximized window.
4
SW_SHOWNOACTIVATE
Displays a window in its most recent size and position. The active window remains active.
5
SW_SHOW
Activates the window and displays it in its current size and position.
6
SW_MINIMIZE
Minimizes the specified window and activates the next top-level window.
7
SW_SHOWMINNOACTIVE
Displays the window as a minimized window. The active window remains active.
8
SW_SHOWNA
Displays the window in its current state. The active window remains active.
9
SW_RESTORE
Activates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when restoring a minimized window.
10
SW_SHOWDEFAULT
Sets the show-state based on the state of the program that started the application.
*These names are for reference only. The -s argument requires a number for its parameter.
Using IsElevated
IsElevated32.exe is for 32-bit Windows platforms and works on 64-bit platforms as well. IsElevated64.exe is included for completeness. IsElevated returns an exit code of 0 if the current program is not elevated, or 1 if the current program is elevated.
IsElevated32 [-q]
- -q
- Runs quietly; that is, it does not display a message box with the elevation status (useful for scripting).
For those aware of my Windows Admin Script Tools package, IsElevated is a GUI version of the IsAdmin.exe tool.
Technical Details
Elevate uses the ShellExecuteEx Windows API with the runas verb.
IsElevated tests whether the security token for the current process contains the Administrators group (the SID S-1-5-32-544), and then it tests whether the group is enabled.
Note that the Elevate and IsElevated programs are not needed in Windows PowerShell since PowerShell can use .NET objects to start processes elevated and test whether the current process is elevated.
Examples
See the TestElevation.vbs and TestElevation.cmd scripts for examples of how to use the programs in scripts.
Version History
1.0 (21 Apr 2010)
- Initial version.