UAC plug-in: Difference between revisions

From NSIS Wiki
Jump to navigationJump to search
(→‎Info: Added link)
 
(32 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{PageAuthor|Anders}}
{{PageAuthor|Anders}}
[[Category:Plugins]]
[[Category:Plugins]]
==Download & Info==
[[Category:Deprecated]]
This plug-in attempts to work around UAC installation problems on Vista.  This plug-in allows your installer to operate with a user level process and an admin level process.  This allows you to accomplish things that would otherwise be very difficult.  For example, you can have an admin level installer launch another process at a user level.  Or you can have an admin level installer create shortcuts at a user level.


It all started in [http://forums.winamp.com/showthread.php?s=&threadid=265780 this thread]. It has been field tested with good results.  It is still definitely in the beta stage (i.e. use at your own risk).
<div style="border: 1px solid #404000; background-color:#FFFF80; color:#000; padding:0.5em;"><b>Note:</b>This plug-in is deprecated. It started out as a proof of concept in the early Vista days and should now be considered abandoned.</div>


Stable aka "Old": [http://stashbox.org/560965/UAC%20v0.0.11d.zip v0.0.11d]


Experimental version: [http://stashbox.org/758458/UAC%20v0.2.2b%20-%2020100103.zip v0.2.2b]
==Plugin Info==
* '''Version:''' 0.2.4c (20150526)
* '''Type:''' Runtime plugin
* '''Character encoding:''' Ansi
* '''Minimum OS:''' Win95/NT4 (Elevation on Win2000+)
* '''Minimum NSIS Version:''' 2.45
* '''License:''' zlib
* '''Download:''' <attach>UAC.zip</attach>




===Basic installation===
==Info==
To install the UAC plugin in your NSIS setup, you just need to copy two files from the above ZIP:
This plug-in attempts to work around UAC installation problems on Win2000+.  This plug-in allows your installer to operate with a user level process and an admin level process ([https://docs.microsoft.com/en-us/windows/win32/secauthz/administrator-broker-model administrator broker model]).  This allows you to accomplish things that would otherwise be very difficult.  For example, you can have an elevated installer instance launch another process as the user.


* For ANSI installers, copy '''UAC.nsh''' into your Include directory (e.g. C:\Program Files\NSIS\Include) and '''UAC.dll''' from Release/A into your Plugins directory (e.g. C:\Program Files\NSIS\Plugins).
It all started in [http://forums.winamp.com/showthread.php?s=&threadid=265780 this thread]. It has been field tested with good results. It is still definitely in the beta stage (i.e. use at your own risk).


* For Unicode installers, copy '''UAC.nsh''' into your Include directory (e.g. C:\Program Files\NSIS\Unicode\Include) and '''UAC.dll''' from Release/U into your Plugins directory (e.g. C:\Program Files\NSIS\Unicode\Plugins).
==Basic Example==
<highlight-nsis>
/*
Basic script for a all users/shared installer.
It runs the installed application as the correct user...
*/


===How it works===
!define S_NAME "UAC_Basic example"
Name "${S_NAME}"
OutFile "${S_NAME}.exe"
RequestExecutionLevel user ; << Required, you cannot use admin!
InstallDir "$ProgramFiles\${S_NAME}"


====Supplying the necessary code====
!include MUI2.nsh
* First, the NSIS script must specify that it should run with user privileges, not admin privileges.
!include UAC.nsh


<highlight-nsis>
!macro Init thing
RequestExecutionLevel user    /* RequestExecutionLevel REQUIRED! */
uac_tryagain:
</highlight-nsis>
!insertmacro UAC_RunElevated
* Next, the most common approach is to let the UAC plugin initialize in the .onInit code:
${Switch} $0
<highlight-nsis>
${Case} 0
; Attempt to give the UAC plug-in a user process and an admin process.
${IfThen} $1 = 1 ${|} Quit ${|} ;we are the outer process, the inner process has done its work, we are done
Function .OnInit
${IfThen} $3 <> 0 ${|} ${Break} ${|} ;we are admin, let the show go on
 
${If} $1 = 3 ;RunAs completed successfully, but with a non-admin user
UAC_Elevate:
MessageBox mb_YesNo|mb_IconExclamation|mb_TopMost|mb_SetForeground "This ${thing} requires admin privileges, try again" /SD IDNO IDYES uac_tryagain IDNO 0
    UAC::RunElevated
${EndIf}
    StrCmp 1223 $0 UAC_ElevationAborted ; UAC dialog aborted by user?
;fall-through and die
    StrCmp 0 $0 0 UAC_Err ; Error?
${Case} 1223
    StrCmp 1 $1 0 UAC_Success ;Are we the real deal or just the wrapper?
MessageBox mb_IconStop|mb_TopMost|mb_SetForeground "This ${thing} requires admin privileges, aborting!"
    Quit
Quit
   
${Case} 1062
UAC_Err:
MessageBox mb_IconStop|mb_TopMost|mb_SetForeground "Logon service not running, aborting!"
    MessageBox mb_iconstop "Unable to elevate, error $0"
Quit
    Abort
${Default}
MessageBox mb_IconStop|mb_TopMost|mb_SetForeground "Unable to elevate, error $0"
Quit
${EndSwitch}


UAC_ElevationAborted:
SetShellVarContext all
    # elevation was aborted, run as normal?
!macroend
    MessageBox mb_iconstop "This installer requires admin access, aborting!"
    Abort


UAC_Success:
Function .onInit
    StrCmp 1 $3 +4 ;Admin?
!insertmacro Init "installer"
    StrCmp 3 $1 0 UAC_ElevationAborted ;Try again?
    MessageBox mb_iconstop "This installer requires admin access, try again"
    goto UAC_Elevate
   
FunctionEnd
</highlight-nsis>
* Before the installer exits, you will need to clean up the plugin.  If you don't, it will leave behind a UAC.dll in the user's %TEMP% folder.  One easy way to clean it up is by supplying the following:
<highlight-nsis>
Function .OnInstFailed
    UAC::Unload ;Must call unload!
FunctionEnd
FunctionEnd


Function .OnInstSuccess
Function un.onInit
    UAC::Unload ;Must call unload!
!insertmacro Init "uninstaller"
FunctionEnd
FunctionEnd
</highlight-nsis>
Remember that if your installer quits before those events can be fired, you should supply a UAC::Unload before the installer quits.


====How the UAC plug-in works with user and admin privileges====
!insertmacro MUI_PAGE_WELCOME
*  When the NSIS installer launches, it has user privileges (as specified by RequestExecutionLevel user).  Immediately, the NSIS installer calls its .onInit code.  (Note, no window is visible yet at this point).  The UAC plugin makes a ''second'' installer process and attempts to elevate it with admin privileges.  If needed, a UAC or Run As dialog is shown to help elevate this second process with admin privileges.  At this point, if you open up Task Manager, you will see two installer processes running.  The user process can be thought of as the outer process, and the admin process the inner process. 
!insertmacro MUI_PAGE_DIRECTORY
* Once elevated, the admin/inner process will display.  This is the installer window that users will see. 
!insertmacro MUI_PAGE_INSTFILES
* Now that you have an admin process, you can continue to let your script do its thing. If you ever need to do something at a user level, you do it through the UAC plugin, and the UAC plugin will run whats needed through the hidden user/outer process.  For example, UAC::Exec can execute something with user privileges and not admin privileges.  Or UAC::ExecCodeSegment can execute an entire function with user privileges.
!define MUI_FINISHPAGE_RUN
 
!define MUI_FINISHPAGE_RUN_FUNCTION PageFinishRun
===Examples===
!insertmacro MUI_PAGE_FINISH
 
Many examples are found in the .zip file above.  If you want a better idea of what this plugin can do, study those examples.  A brief overview of two simple examples are given here:
====Creating a user shortcut====
 
http://www.dokuwiki.org/lib/images/smileys/fixme.gif
Invalid for the latest release, use !insertmacro instead (section below).


!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES


!insertmacro MUI_LANGUAGE "English"


UAC_RealWorldExample.nsi does:


<highlight-nsis>
Function PageFinishRun
Function CreateShortcuts
; You would run "$InstDir\MyApp.exe" here but this example has no application to execute...
  CreateShortcut "$Desktop\${APPNAME}.lnk" "$Windir\Notepad.exe"
!insertmacro UAC_AsUser_ExecShell "" "$WinDir\notepad.exe" "" "" ""
FunctionEnd
FunctionEnd


Section "Desktop Shortcut"
Section
  GetFunctionAddress $0 CreateShortcuts
SetOutPath $InstDir
  UAC::ExecCodeSegment $0
# TODO: File "MyApp.exe"
WriteUninstaller "$InstDir\Uninstall.exe"
SectionEnd
SectionEnd
</highlight-nsis>


In this example, we would want to run the CreateShortcuts function with user privileges, so it can create a user-level shortcut.  So first, define the function.  Then use GetFunctionAddress to get the address of that function.  Then, call UAC::ExecCodeSegment to ask the outer/user process to run that function.  Since the function will be run at a user level, it will create a shortcut for the user instead of for the administrator.
Section Uninstall
 
SetOutPath $Temp ; Make sure $InstDir is not the current directory so we can remove it
====Launching an application with user privileges====
# TODO: Delete "$InstDir\MyApp.exe"
<highlight-nsis>
Delete "$InstDir\Uninstall.exe"
; !insertmacro UAC_AsUser_ExecShell <Command> <File> <Parameters> <WorkingDir> <ShowWindow>
RMDir "$InstDir"
!insertmacro UAC_AsUser_ExecShell 'open' '$INSTDIR\${APPFILE}' '-firstrun' '$INSTDIR' ''
SectionEnd
</highlight-nsis> 
 
Where $INSTDIR\${APPFILE} is the path to the file you want to launch.
 
If you use the MUI skin and have the installer launch the app for you, you will need to do a little more work. 
 
<highlight-nsis>
!define MUI_FINISHPAGE_RUN
!define MUI_FINISHPAGE_RUN_FUNCTION ExecAppFile
 
Function ExecAppFile   
    !insertmacro UAC_AsUser_ExecShell 'open' '$INSTDIR\${APPFILE}' '-firstrun' '$INSTDIR' ''
FunctionEnd
</highlight-nsis>
</highlight-nsis>


Keep in mind that you still have to define MUI_FINISHPAGE_RUN (as empty) otherwise MUI won't provide the option at all.
==Important Notes==
 
# If you need to use the UAC plugin for the uninstaller as well, you will need to initalize the UAC plugin for the uninstaller, such as through un.onInit.
===Important Notes===
 
# If you need to use the UAC plugin for the uninstaller as well, you will need to initalize the UAC plugin for the uninstaller, such as through un.onInit. Remember to run clean it up with UAC::Unload before your uninstaller exits.  Great places to clean it up are un.OnUnInstFailed and un.OnUnInstSuccess
# The outer/user process does not display any output as to what occurred.  For example, if you have the outer/user process create a shortcut, and it fails, the inner/admin process currently visible will not display anything to indicate that a problem occurred.  This is because the outer/user process does not yet communicate back to the inner/admin process.
# The outer/user process does not display any output as to what occurred.  For example, if you have the outer/user process create a shortcut, and it fails, the inner/admin process currently visible will not display anything to indicate that a problem occurred.  This is because the outer/user process does not yet communicate back to the inner/admin process.
# When a standard or limited user supplies administrator information into the Run As dialog, you may experience permissions trouble with any extracted file.  For example, if a Windows 2000 standard user supplies administrator info into the Run As dialog, and the NSIS installer extracts an .exe file, then trying to call that .exe through an Exec can fail.  If this is a problem, you will want to use the [[AccessControl_plug-in|AccessControl plug-in]].
# When a standard or limited user supplies administrator information into the Run As dialog, you may experience permissions trouble with any extracted file.  For example, if a Windows 2000 standard user supplies administrator info into the Run As dialog, and the NSIS installer extracts an .exe file, then trying to call that .exe through an Exec can fail.  If this is a problem, you will want to use the [[AccessControl_plug-in|AccessControl plug-in]].
===Tested Environments===
This plugin has been tested under the following environments:
* Windows Vista - UAC On - Administrator
* Windows Vista - UAC Off - Administrator
* Windows Vista - UAC On - Standard User - User supplies administrator info into the UAC dialog
* Windows Vista - UAC On - Standard User - User does not supply administrator info into the UAC dialog
* Windows Vista - UAC Off - Standard User - User supplies administrator info into the Run As dialog
* Windows Vista - UAC Off - Standard User - User does not supply administrator info into the Run As dialog
* Windows XP - Administrator
* Windows XP - Limited User - User supplies administrator info into the Run As dialog
* Windows XP - Limited User - User does not supply administrator info into the Run As dialog
* Windows 2000 - Administrator
* Windows 2000 - Standard User - User supplies administrator info into the Run As dialog
* Windows 2000 - Standard User - User does not supply administrator info into the Run As dialog
* Windows 95 & 98 were tested in early builds and hopefully still work (No elevation here for obvious reasons)
Windows ME & NT4 are untested, but should work. (If you have tested on one of these OS'es, please report results here or on the forum)

Latest revision as of 14:32, 21 January 2022

Author: Anders (talk, contrib)


Note:This plug-in is deprecated. It started out as a proof of concept in the early Vista days and should now be considered abandoned.


Plugin Info

  • Version: 0.2.4c (20150526)
  • Type: Runtime plugin
  • Character encoding: Ansi
  • Minimum OS: Win95/NT4 (Elevation on Win2000+)
  • Minimum NSIS Version: 2.45
  • License: zlib
  • Download: UAC.zip (50 KB)


Info

This plug-in attempts to work around UAC installation problems on Win2000+. This plug-in allows your installer to operate with a user level process and an admin level process (administrator broker model). This allows you to accomplish things that would otherwise be very difficult. For example, you can have an elevated installer instance launch another process as the user.

It all started in this thread. It has been field tested with good results. It is still definitely in the beta stage (i.e. use at your own risk).

Basic Example

/*
Basic script for a all users/shared installer.
It runs the installed application as the correct user...
*/
 
!define S_NAME "UAC_Basic example"
Name "${S_NAME}"
OutFile "${S_NAME}.exe"
RequestExecutionLevel user ; << Required, you cannot use admin!
InstallDir "$ProgramFiles\${S_NAME}"
 
!include MUI2.nsh
!include UAC.nsh
 
!macro Init thing
uac_tryagain:
!insertmacro UAC_RunElevated
${Switch} $0
${Case} 0
	${IfThen} $1 = 1 ${|} Quit ${|} ;we are the outer process, the inner process has done its work, we are done
	${IfThen} $3 <> 0 ${|} ${Break} ${|} ;we are admin, let the show go on
	${If} $1 = 3 ;RunAs completed successfully, but with a non-admin user
		MessageBox mb_YesNo|mb_IconExclamation|mb_TopMost|mb_SetForeground "This ${thing} requires admin privileges, try again" /SD IDNO IDYES uac_tryagain IDNO 0
	${EndIf}
	;fall-through and die
${Case} 1223
	MessageBox mb_IconStop|mb_TopMost|mb_SetForeground "This ${thing} requires admin privileges, aborting!"
	Quit
${Case} 1062
	MessageBox mb_IconStop|mb_TopMost|mb_SetForeground "Logon service not running, aborting!"
	Quit
${Default}
	MessageBox mb_IconStop|mb_TopMost|mb_SetForeground "Unable to elevate, error $0"
	Quit
${EndSwitch}
 
SetShellVarContext all
!macroend
 
Function .onInit
!insertmacro Init "installer"
FunctionEnd
 
Function un.onInit
!insertmacro Init "uninstaller"
FunctionEnd
 
!insertmacro MUI_PAGE_WELCOME
!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES
!define MUI_FINISHPAGE_RUN
!define MUI_FINISHPAGE_RUN_FUNCTION PageFinishRun
!insertmacro MUI_PAGE_FINISH
 
!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES
 
!insertmacro MUI_LANGUAGE "English"
 
 
Function PageFinishRun
; You would run "$InstDir\MyApp.exe" here but this example has no application to execute...
!insertmacro UAC_AsUser_ExecShell "" "$WinDir\notepad.exe" "" "" ""
FunctionEnd
 
Section
SetOutPath $InstDir
# TODO: File "MyApp.exe"
WriteUninstaller "$InstDir\Uninstall.exe"
SectionEnd
 
Section Uninstall
SetOutPath $Temp ; Make sure $InstDir is not the current directory so we can remove it
# TODO: Delete "$InstDir\MyApp.exe"
Delete "$InstDir\Uninstall.exe"
RMDir "$InstDir"
SectionEnd

Important Notes

  1. If you need to use the UAC plugin for the uninstaller as well, you will need to initalize the UAC plugin for the uninstaller, such as through un.onInit.
  2. The outer/user process does not display any output as to what occurred. For example, if you have the outer/user process create a shortcut, and it fails, the inner/admin process currently visible will not display anything to indicate that a problem occurred. This is because the outer/user process does not yet communicate back to the inner/admin process.
  3. When a standard or limited user supplies administrator information into the Run As dialog, you may experience permissions trouble with any extracted file. For example, if a Windows 2000 standard user supplies administrator info into the Run As dialog, and the NSIS installer extracts an .exe file, then trying to call that .exe through an Exec can fail. If this is a problem, you will want to use the AccessControl plug-in.