Step 4: Redesign Your UI for UAC Compatibility

Step Four: Redesign Your Application's User Interface for UAC Compatibility

Use the guidelines in this section to develop your application's user interface for UAC compatibility. Closely adhering to these guidelines in your application's development will ensure that your application will have a consistent and predictable user experience in Windows Vista®.

• Impact of UAC on the Windows User Experience

• Goals of the UAC User Experience

• Elevation Prompt

• User experience process flow

• Elevation entry points

• User interface implementation

• When to add a shield icon to your application's user interface

• Key decisions for administrator-only applications

Important

Simply refractoring your application's user interface will not fulfill the requirements for UAC compatibility. Your application's core functionality must comply with the Windows Vista standard user model requirements. These requirements were detailed in the previous step, Step 3: Redesign for UAC Compatibility (UAC).

Impact of UAC on the Windows User Experience

The biggest and most immediate impact on the user experience will be felt by administrators. Administrator users will now need to provide permission to accomplish administrative tasks. Coupled with that, standard users will now gain the ability to perform administrative tasks within the currently logged in session by providing valid administrator credentials.

Goals of the UAC User Experience

The overall goal for UAC user experience is to provide predictability in the user experience:

• For an administrator, this means that the user always know when he/she will need to give permission to run an elevated task.

This is the act of requesting the user's own administrator access token so that he/she can make administrator-required changes.

• For standard users, this means that they will know when they:

  • Will need to provide administrator credentials (home and unmanaged environments) for administrative tasks.

  • OR When they cannot complete a task (managed environments where elevation is explicitly disallowed) and must contact the help desk.

Design Goals

The following list comprises the UAC design goals.

Eliminate Unnecessary Elevation

Users should have to elevate only to perform tasks that require an administrator access token. All other tasks should be designed to eliminate the need for elevation. Pre-Windows Vista software often requires an administrator access token unnecessarily by writing to the HKEY_LOCAL_MACHINE or HKEY_CLASSES_ROOT registry sections or to the Program Files or Windows system folders.

Be Predictable

Administrators need to know which tasks require elevation. If they cannot predict the need for elevation accurately, they are more likely to give consent for administrative tasks when they should not. Standard users need to know which tasks require an administrator to perform or cannot be performed at all in managed environments.

Require Minimal Effort

Tasks that require a higher privileged access token should be designed to require a single elevation. Tasks that require multiple elevations quickly become tedious.

Revert to Standard User

Once a task that requires a higher level of access token is complete, the program should revert to the standard user state.

Elevation Prompt

The elevation prompt is built upon an existing Windows user interface. The elevation prompt displays contextual information about the executable requesting elevation, and the context is different depending on whether the application is Authenticode signed. The elevation prompt is seen in two variations: the consent prompt and the credential prompt.

Consent Prompt

The consent prompt is displayed to administrators in Admin Approval Mode when they attempt to perform an administrative task. This is the default user experience for administrators in Admin Approval Mode and can be configured in the local Security Policy Manager snap-in (secpol.msc) and with Group Policy.

The following figure is an example of a User Account Control consent prompt.

User Account Control consent prompt

Credential Prompt

The credential prompt is displayed to standard users when they attempt to perform an administrative task. This is the default user experience for standard users and can be configured in the local Security Policy Manager snap-in (secpol.msc) and with Group Policy.

The following figure is an example of a User Account Control credential prompt.

User Account Control credential prompt

Default Elevation Prompt Consent Policy for Windows Vista

The following table outlines the default prompt style for each user account type in Windows Vista.

Default elevation prompt behavior

User Account Type	Elevation Prompt Setting
Standard user	Prompt for credentials
Administrator account in Admin Approval Mode	Prompt for consent

User Experience Process Flow

The UAC user experience process flow consists of three distinct components:

1. Elevation entry point (for example, a control or link that displays the UAC shield icon).

2. Elevation prompt (a request for consent or for administrator credentials).

3. Elevated process.

The following example workflow summarizes how the preceding components are related:

1. An administrator in Admin Approval Mode logs on to a Windows Vista computer.

2. The user then decides to add another administrator user for the computer.

3. The user clicks Start, clicks Control Panel, and then clicks the link in the Security section entitled Allow a program through Windows Firewall, which is displayed inline with a shield icon.

4. A consent prompt appears requesting the user for approval.

5. The user clicks Continue and the elevated process is created.

6. In Windows Firewall Settings, the user modifies the Windows Firewall settings and then clicks OK, which terminates the elevated process.

7. The user continues to work on the computer as a standard user.

Note

Elevation entry points do not remember state (e.g. when navigating back from a shielded location or task), as well as the entry point will not remember that elevation has occurred. As a result, the user will need to re-elevate to enter the task/link/button again.

Elevation Entry Points

For entry points, the shield icon will be attached to certain controls (e.g. buttons, command links, hyperlinks) to indicate that the next immediate step requires elevation.

Shield Icon

The shield icon is the primary user interface decoration for a UAC elevation point. This icon signifies security related activities in Windows Vista and previous versions of Windows, and this relationship is continued in Windows Vista.

The following figure is an example of the shield icon.

Shield icon

The shield icon will play a critical part in all three components of the UAC user experience.

When viewing the system with Windows Explorer, any application that is marked to request an administrator access token when it is launched will automatically be decorated with a shield glyph over its icon. This permits users to know which applications, when launched, will request elevation.

Shield icon properties:

• Consistent appearance throughout the entire UAC user experience.

• Does not reflect any visual state (e.g. active, hover, disabled, etc.).

• Does not remember state.

There are three consistent control styles that an entry point marked with a shield icon can take within the user experience:

• UAC button.

• UAC hyperlink.

• UAC command link.

These styles apply to all scenarios where these user interface elements can appear such as Wizards, property pages, control panels, explorers, etc. Each of the styles implies that an elevation prompt will immediately be displayed after the user clicks a UAC user interface control.

A fourth UAC user interface entry point, the UAC icon overlay, is also discussed in this section. Whether an executable receives an icon overlay or not is not controlled by the application developer. Windows Vista overlays a shield icon on applications' icons for executables that have requestedExecutionLevel set to requireAdministrator.

UAC Shield Button

The UAC shield button should be used in any user interface button that, when pressed, will require the elevation prompt to prompt the user for approval or credentials.

UAC shield buttons can be used as commit buttons (e.g. Next in a Wizard) or as a button to display an additional settings user interface (e.g. Change Settings in a property dialog).

The UAC shield button consists of two user interface components:

• Shield icon

• Text label

The UAC shield button is packaged in a manner so that developers can use it in the place of a normal button. The UAC button also supports rendering the shield icon on the left or right side of the text label. In addition, developers will have the option to hide/show the shield icon while the UAC button is displayed.

The following screenshot is an example of a UAC shield button.

UAC shield button

UAC Hyperlink

The UAC hyperlink should be used in any user interface hyperlink that, when clicked, will require the elevation prompt to prompt the user for approval or credentials.

A UAC hyperlink consists of the following components:

• Shield icon

• Hyperlink control

The UAC hyperlink is not packaged with the shield icon for a developer to use. Developers will need to get the shield icon resource and render it next to the hyperlink.

The following screenshot is an example of a UAC hyperlink.

UAC hyperlink

UAC Command Link

The UAC command link should be used in any user interface button that, when clicked, will require the elevation prompt to prompt the user for approval or credentials.

UAC command links should only be used as commit buttons (e.g. "Do this option" in a dialog box).

The UAC command link consists of the following components:

• Shield icon

• Standard command link components

• Link text

• Note text

The UAC command link is packaged in a way where a developer can use a UAC command link in the place of a normal command link. The UAC command link supports rendering the shield icon on the left or right side of the command link.

The following is an example of a UAC command link.

UAC command link

Icon Overlays

In Windows Vista, if an executable file requires elevation to launch, then the executable's icon should be "stamped" with a shield icon to indicate this fact. The executable's application manifest must designate a requestedExecutionLevel of requireAdministrator to designate the executable as requiring a full administrator access token. The shield icon overlay will also be automatically placed on executables that are deemed to require elevation, as per the installer detection heuristics. For example, a file named setup.exe will automatically receive a shield icon overlay, even if the executable does not have an embedded application manifest.

The following figure is an example of a UAC icon overlay.

UAC icon overlay

Note

Guidance about how to create and embed an application manifest with an executable is provided in the Step 6: Create and Embed an Application Manifest (UAC) section of this document.

User Interface Implementation

Shield Icon Implementation and APIs

This section provides preliminary information on the icons and APIs available to developers as they migrate or implement new administrative application functionality.

Shield icon implementation and APIs

Icon	API
Shield	User resource: IDI_SHIELD
Button	Button_SetElevationRequired(hwndButton)
Syslink / Hyperlink	Layout IDI_SHIELD next to syslink
Command link	Load IDI_SHIELD and set as command link icon
Context menu	Icon support in DefCM for static commands

How Do I…

• Add a shield icon to the user interface?

• Add a shield icon to a button?

• Add a shield icon to a Windows Installer button?

• Add a shield to a "Next" button control on a Wizard?

• Add a shield icon to a task dialog button?

• Elevate a modal dialog?

Add a Shield Icon to the User Interface

Add a small icon:

#include <shellapi.h>
SHSTOCKICONINFO sii;
sii.cbSize = sizeof(sii);
SHGetStockIconInfo(SIID_SHIELD, SHGSI_ICON | SHGSI_SMALLICON, &sii);
hiconShield  = sii.hIcon;

Add a large icon:

SHSTOCKICONINFO sii;
sii.cbSize = sizeof(sii);
SHGetStockIconInfo(SIID_SHIELD, SHGSI_ICON | SHGSI_LARGEICON, &sii);
hiconShield  = sii.hIcon;

Add an icon of custom size:

SHSTOCKICONINFO sii;
sii.cbSize = sizeof(sii);
SHGetStockIconInfo(SIID_SHIELD, SHGSI_ICONLOCATION, &sii);
hiconShield  = ExtractIconEx(sii. ...);

Note

Generally, you should not add the shield icon directly to your user interface. Using one of the proceeding methods of embedding the shield icon in a control is recommended. Additionally, simply adding a shield icon in your user interface will not ensure UAC compatibility. You must also refractor the entirety of your application's user experience (add a requestedExecutionLevel, fix any standard user application compatibility problems, and ensure that the user interface is user friendly and UAC compatible).

Add a Shield Icon to a Button

The standard button control (PUSHBUTTON, DEFPUSHBUTTON) has been enhanced to allow you to add an icon along with the displayed text, without requiring the BS_ICON or BS_BITMAP styles to be set.

To display the shield icon, call the following macro (defined in commctrl.h):

Button_SetElevationRequiredState(hwndButton, fRequired);

Note

hwndButton is the HWND of the button; fRequired determines whether to show (TRUE) or hide (FALSE) the UAC shield icon.

Add a Shield Icon to a Windows Installer Button

Windows Installer dialogs authored using the internal table support can add a shield to the last button of the user interface dialog sequence by setting the ElevationShield attribute on the control.

Add a Shield Icon to a "Next" Button on a Wizard

Important

Displaying the UAC shield icon the "Next" button is only supported in AeroWizards (PSH_AEROWIZARD).

To display the shield icon on the "Next" button for a specific page in an AeroWizard, use the following code:

case WM_NOTIFY:
    if (reinterpret_cast<NMHDR*>(lParam)->code == PSN_SETACTIVE)
    {
        // Show next button
        //
        // Note new wParam flag -- when PSWIZBF_ELEVATIONREQUIRED flag
        // is specified, it indicates that the next page will require
        // elevation, so if the next button is being shown, show it as
        // a shield button.

        SendMessage(GetParent(hwndDlg), 
                    PSM_SETWIZBUTTONS, 
                    PSWIZBF_ELEVATIONREQUIRED, 
                    PSWIZBF_NEXT);

        // return 0 to accept the activation
        SetWindowLong(hwndDlg, DWLP_MSGRESULT, 0); 
    }
    break;

Add a Shield Icon to a Task Dialog Button

Warning

A task dialog button should never require a UAC shield icon. The "press" action on a task dialog button is expected to commit/cancel and dismiss the task dialog. It would be strange for such a button to then display the elevation prompt to the user.

Elevate a Modal Dialog

Use the elevation moniker to elevate the COM object representing the modal dialog.

Tasks:

• Move the dialog box into a COM object.

• Expose a ShowDialog() method.

• Use the API CoCreateInstanceAsAdmin() to create the COM object and call ShowDialog().

This API will run an instance of the COM object as administrator after going through the elevation process.

Note

A version of this API that is more complicated to call is available. A simplified version will be available in a later version of Windows Vista.

User Education and Assistance Guidelines

When a user interface has been refractored and put behind a button, ISVs should evaluate whether a change to the button name is warranted Microsoft strongly advises against using Advanced as a button label for elevation tasks. Instead, use more descriptive and understandable labels like Change settings or a term that suggests what is behind the button.

Guidelines for Administrator-Only User Interface

If an application will always be launched by an administrator, then you do not need to add additional shields within the application's user interface. This is because the application will be elevated and everything it does will be elevated and thus does not need further elevation.

Note

If you have links to other administrator user interface in your administrator-only user experience, the user interface will launch its target elevated. Therefore, you do not need to put any shields in an application that is solely administrative.

When to Add the Shield Icon to Your Application's User Interface

An Administrative Choice Application

An Elevated Process or COM Object

An elevated process or COM object launches without requiring elevation. Those items in the user interface that require an administrator access token are decorated with a shield icon to identify this requirement. The shield icon decoration indicates to the user that using that feature will require administrator approval. When the application detects that one of these buttons has been selected, it has the following two choices:

• The application launches a second program using ShellExeucute() to perform the administrative task. This second program would be marked with a requestedExecutionLevel of requireAdministrator, thus causing the user to be prompted for approval. This second program would be running with a full administrative access token and would be able to perform the desired task.

OR

• The application launches a COM object using CoCreateInstanceAdmin(). This API would launch the COM object with a full administrative access token following approval and this COM object would be able to perform the desired task.

This method provides the richest user experience and is the preferred method of dealing with administrative functionality.

The following list details requirements for an elevated process or COM object:

• The control panel should implement the shield decoration and its required architecture.

• The developer must determine where the shield should go on the user interface.

• The developer must do the architectural work to separate the business logic into a COM object from the user interface object.

• The developer must call into the UAC elevation process when the OnClick event for the shield icon is detected.

The following list details benefits of properly designing an elevated process or COM object:

• This is the best overall user experience for both user types. The user interface will launch, viewable to everyone, and all UAC functionality on that user interface will be accessible to everyone. Only when an administrator task is required does the user attempt to elevate to complete the task.

• Doing this work now will make you fully UAC–compliant moving forward.

• The user interface/COM separation is a good architectural practice.

Clicking on a shield icon causes the application to launch either an elevated program or an elevated COM object to perform the task.

Administrator-Only Application

In this instance, the application’s initial launch requires administrator approval. This method is called "prompt before launch." Once launched, the application is running with a full administrator access token and can therefore perform the desired administrative tasks. This method requires the least amount of work for the developer, and the application’s manifest is marked with a requestedExecutionLevel of requireAdministrator.

Important

While this does require the least amount of work for the developer, please note that, just like other administrative applications in Windows Vista, administrators will have to elevate in order to use this application and that standard users will be unable to use the application unless they have access to administrator credentials for an administrator account on the computer.

The following list details requirements for administrator-only applications:

• The application manifest should contain a requestedExecutionLevel marking set to requireAdministrator.

• The user is prompted for administrator approval prior to Windows launching the application with a full administrative access token.

The following list details benefits of properly designing an administrator-only application:

• The operating system does not have to "guess" if your setup application is an administrative application.

• Standard users will automatically be given a hint that the operation is an administrative operation. For example, when you see the icon for an application marked requireAdministrator, the icon has a shield embedded in the icon.

• On Windows Vista, if you mark your application as requireAdministrator you know that, once it is launched, it will be running with a full administrator access token. Users must elevate to run the application (either as an administrator in Admin Approval mode or by using Run as administrator).

Note

Marking an application requireAdministrator does NOT silently elevate the application. The user will still have to give elevation consent to start the application. There is no way to mark an application in Windows Vista to silently elevate.

The following list details points of consideration for designing an administrator-only application:

• This user experience means that all users will see an elevation prompt (either the credential prompt or the consent prompt) prior to the user interface even being visible. That also means no one is able to simply view the current settings until after authenticating with administrator credentials.

• If you are marking requireAdministrator on a setup application, you should be aware that the user that is running the setup is different from the user that may use the application. Therefore, you should not modify HKEY_CURRENT_USER (HKCU) and other per-user settings, such as writing to the user profile, during your administrative setup.

Important

You must assume that the user running the administrative application is different from the normal user on the computer.

Executables that require an administrator access token are marked with a shield icon overlay.

Mixed Application

A mixed application is one that can be run by users—all users of the computer (standard users, administrators in Admin Approval Mode, and those in between like Backup Operators). This is also a "prompt before launch" application. The application will run with the invoker's access token and will launch normally for standard users (no elevation prompt).The program must then modify its behavior at run time to disable those features that would not be available to the user based on the access token obtained.

A mixed application does not have the ability to obtain additional administrative privileges once launched; therefore, it does not provide the flexibility of the elevated process or COM object method described previously. This is most useful for applications that require an access token above that of a standard user, but less than that of a full administrator.

For example, the Microsoft Management Console (MMC) is marked highestAvailable. If a true standard user runs the MMC, MMC will launch as a standard user application without any elevation attempt or prompt. If the user has a filtered access token, such as an administrator in Admin Approval Mode or a Backup Operator, the operating system will prompt the user for consent to launch MMC with the user's "highest" available privilege. In the case of a standard user who has Backup Operator privileges, after elevation, MMC will be launched with standard user + Backup Operator, but nothing more. If an administrator launches MMC, after elevation, MMC will be running as a full administrator application.

The benefit of properly designing a mixed application is that the application is available to all users of the system, even though some functionality may be disabled.

The following list details points of consideration for designing mixed applications:

• The developer must dynamically change the behavior of the application based on the user's available administrative Windows privileges and user rights.

• The standard user is prevented from ever being able to act on the administrative-level functions on the user interface. There is no potential for prompt elevation once the program is running (the administrators must elevate before opening the user interface).

Note

There is one workaround for the previous bullet point. An administrator can launch an elevated command prompt on the standard user's computer and run the application from the command prompt. For example, right-click the command prompt, select Run as administrator, and then type "applicationname.exe" in the command prompt.

The user experience is branched between the standard user and the administrator in Admin Approval Mode.

Example Mixed Application: Backup Application

The application could be launched by a member of the Backup Operators group. The program would then verify that the highest level of administrative Windows privileges and user rights available from the user is sufficient for the program's operation. For more information about program launch behavior, see the Application Manifest Marking and Application Launch Behavior section of this document.

Key Decisions for Designing Administrator-Only Applications

Back-End Business Objects

This section provides an overview of the three models a developer can choose when developing an administrative application that provides the best user experience.

• The Admin Broker model.

• The Back-End Service model.

• The Admin COM Object model.

Admin Broker Model

In the Admin Broker model, the application is broken into two independent executables—a standard user executable and an administrative executable. The developer, using an application manifest, marks the standard user program with a requestedExecutionLevel of asInvoker and marks the administrative program with a requestedExecutionLevel of requireAdministrator. A user will launch the standard user program first. When the user attempts to perform an operation that the standard user program knows requires a full administrator access token, the standard user program performs a ShellExecute() and launches the administrative program. The Windows ShellExecute() API looks at the application manifest and requests approval from the user before running the application with the user's full administrator access token. The administrative program can then perform the administrative tasks.

Note

The administrative executable program may enable inter-process communication with a standard user executable using shared memory, local Remote Procedure Call (RPC), or named pipes. If the administrative program does enable communication with the standard user executable, the developer needs to use good security practice to validate all inputs from the lower privilege program.

Note

There is no communication channel between the two programs once the second program launches.

The following list details uses for the admin broker model:

• Wizards – When the Hardware Wizard realizes that the required driver is not installed on the computer or located in the enterprise's approved location, it needs an elevated application with the ability to move a driver into the computer store.

• Autorun.exe calling Setup.exe – The first time you put in a game CD, the required operation from Autorun.exe is to set up the application. The second time you insert the CD, the default operation is to play the game.

A benefit to using the admin broker model is that it is probably the easiest mechanism for the developer to implement.

The following list details some drawbacks to using the Admin Broker Model:

• The transitions from application to application can be confusing to the user. It can be hard to keep the user apprised of why a new application is "popping up" on the monitor.

• In addition, state is harder to pass between these two applications. For example, you would not use this to pass state between a standard user control panel (CPL) and its administrator counterpart simply to allow the same CPL to have administrative and standard user functionality. The standard user CPL would have to store its state somewhere.

• Often, there is a lot of replicated code when splitting the functionality between two programs.

To implement the admin broker model, create two programs (one standard user and one administrative), mark them with the appropriate application manifest requestedExecutionLevel, and then launch the administrative program from the standard user program using ShellExecute().

The Back-End Service Model

In the back-end service model, the application is again broken into two independent executables—a standard user executable that provides the user interface to the user and a back-end service running on the system. The front-end application is marked with a requestedExecutionLevel of asInvoker and the back-end service is running as SYSTEM. Communication between the application and the back-end service is accomplished with RPC.

One use for the back-end service model is to control programs that could impact the system, such as antivirus programs or anti-spyware). The front-end application provides the means by which the logged on user can control aspects of the service.

A major benefit of using the back-end service model is that no elevation prompting is required.

The following list details some drawbacks to using the back-end service model:

• The service needs to limit the types of activities the front-end application can tell it to do. For example, an antivirus service may allow a standard user to initiate a scan of the system but not to disable real-time virus checking.

• Adding an unnecessary service to the system can impact the entire system. Ensure that your service is truly necessary for your Windows Vista implementation and that the service is properly architected.

To implement the back-end service model, create a standard user front-end application and a back-end service. Install the service in the system during product installation time.

The Admin COM Object Model

This model is included here, but was discussed in detail previously in this document. The admin COM object model allows dynamic administrative elevation to perform specific operations from within an application or control panel.

A major benefit for using the admin COM object model is that it presents the best user experience for the user.

The following list details some drawbacks to using the admin COM object model:

• Requires the most work for the developer as each application feature has to be evaluated and tested for administrator functionality and that function has to be provided by a back-end COM object.

• User needs to provide elevation approval.

• The resulting "unit" of standard user application and admin backend COM object is now "drivable" and is not protected by UIPI and other isolation mechanisms.

To implement the admin COM object model, create a standard user front-end application and launch elevated back-end COM objects to perform administrative tasks.

See Also

Concepts

Designing UAC Applications for Windows Vista