Elevation Of Privileges

## Elevation Of Privileges |

### 1. Introduction

Most operating systems have the concept of normal users and administrators. While regular applications can run with limited privileges, installers often need full administrator privileges because they make modifications to the system that are not granted to limited users. The required privileges depend on two factors: The operating system and the type of operations that are performed by the installer. The "Request privileges" action that is present in the "Startup" sequence of both installers and uninstallers by default takes care of elevating the privileges to the required level and optionally terminating the installer with an error message if the required privileged cannot be obtained. Due to the differences for the different operating systems, this configuration is made separately for Windows, Max OS X and Unix.

For the installer and the uninstaller, the privileges should be the same. This is why by default the "Request privileges" action in the uninstaller is a link to the action in the installer. If you have more complex requirements, you can have multiple "Request privileges" actions with appropriate condition expressions, each with a link in the uninstaller.

### 2. Windows privileges

Since Windows Vista, "User Account Control" (UAC) limits privileges for all users by default. An application can request full privileges, with different effects for normal users and admin users: A normal user cannot be elevated to full privileges, so the user has to enter credentials for a different administrator account. A normal user is not likely to have these credentials, so by default the "Request privileges" action does not try to obtain full privileges for normal users. An admin user can be elevated. A UAC prompt will be shown in this case and the user simply has to agree in order to elevate privileges for the installer. Since it is not possible to write to the the program files directory without elevated privileges, this elevation is performed by default. With the "Try to obtain full privileges if admin user" and the "Try to obtain full privileges if normal user" properties in the "Windows" category, you can configure this behavior according to your own needs.

By default, the installer will fail if the the requested privileges cannot be obtained. You can deselect the "Show failure if requested privileges cannot be obtained" property in the Windows category to continue and let the user install into the user home directory or another writable directory.

Under some circumstances, for example if you want to manage services in your installer, you absolutely require full privileges. In this case, you can select the "Try to obtain full privileges if normal user" property in the Windows category. When you insert a service action and the elevation properties are not selected, you will be asked whether the necessary changes should be made automatically.

### 3. Mac OS X privileges

Similar to Windows, Mac OS X limits privileges for all users by default and normal users and admin users behave differently with respect to privilege elevation: A normal user cannot be elevated to full privileges, so the user has to enter the root password. A normal user is not likely to have the root password, so by default the "Request privileges" action does not try to obtain full privileges for normal users. To elevate an admin user, an authenticate dialog will be shown and users have to enter their own password. Contrary to Windows, admin users can always write to the `/Applications` directory, even without full privileges. That's why on Mac OS X no elevation of privileges is requested by default.

Like on Windows, the installer will fail by default if the the requested privileges cannot be obtained. In the default setting this has no effect, because privileges are never requested.

Service installations require full privileges, so the "Try to obtain full privileges if admin user" and the "Try to obtain full privileges if normal user" properties in the Mac OS X category should be selected in that case. Again, service actions will suggest to make the necessary changes automatically when they are inserted into the project.

### 4. Unix privileges

install4j does not support elevation of privileges on Linux and Unix. Partly this is due to the different incompatible systems of elevation, most notably "su" and "sudo" which cannot be easily detected. If full privileges are required, the user has to elevate the installer manually, either with "su" or with "sudo" or with the corresponding GUI tools. In this case, the "Show failure if current user is not root" has to be selected, so that an error message is shown if the installer is not started as root.

### 5. Elevation mechanism

There are two strategies for elevating privileges: Either restart the main installation process, or start a helper process with full privileges. The UAC dialog on Windows and the authenticate dialog on Mac OS X are the same in both cases. However, the "Install Files" action is always executed in the main installation process. On Windows, where you only can write to the program files directory with full privileges, the preferred strategy is to elevate the main installation process. On Mac OS X, it is possible to write to `/Applications` for admin users, so the preferred strategy on Mac OS X is to start an elevated helper process. Also, the restart of the main installation process on Mac OS X is noticeable to the user in the dock.

If the "Request admin privileges" action performs a restart, all response file variables are transferred to the new installer process. This means that the "Request admin privileges" action does not necessarily have to be located in the "Startup" sequence. You could gather some user input and then decide if you need elevated privileges or not later on.

For your own scripts or custom code, the API offers a way to push a piece of code to the elevated helper process or to the original process if they exist. This is done by wrapping the code in a `com.install4j.api.context.RemoteCallable` and calling `context.runElevated(...)` for the elevated helper process and `context.runUnelevated(...)` for the original process with the `RemoteCallable`. The `RemoteCallable` must be serializable, so its fields can be transferred to the other process. Its `execute()` method that contains the code returns a `Serializable` so you can return a result to the calling process. Several actions in install4j use this mechanism, as explained in the next section.

### 6. Elevation and Unelevation of single actions

The following elements in install4j support the elevated helper process automatically:

- Service actions
- Actions that add rights on Windows
- Creating a user with the "Windows user selector" form component
- Methods in the `com.install4j.api.windows.WinUser` class

If the action fails with limited privileges, it will be repeated with full privileges in the elevated helper process automatically.

If the main installation process is elevated, the original process is kept alive. It waits for the elevated process to finish and services requests for actions that should be executed as the original user. There are several actions that are automatically executed as the original user:

- "Show URL" action
- "Show file" action
- "Execute launcher" action

In these cases, external process are started that should not be run with full privileges, both for security concerns and for usability reasons. For example, on Windows Vista and higher, drag and drop does not work between applications with limited privileges and applications with full privileges.

The "Run executable or batch file" and the "Uninstall previous installation" actions can both elevate or unelevate the executed process. Their "Execution account" property allows you to either execute them in the context of the main installation process ("Run as is"), push them to the elevated helper process ("Run as admin if possible") or push them to the original process that services requests by the elevated main installation process.