Step 6: Create and Embed an Application Manifest (UAC)
Step Six: Create and Embed an Application Manifest with Your Application
In Windows Vista®, the correct way to mark your applications is to embed an application manifest within your program that tells the operating system what the application needs. In the Windows Vista release, there are provisions to allow non-manifested or unsigned code to run with a full administrative access token.
Note
In future releases, the only way to run an application elevated will be to have a signed application manifest that identifies the privilege level that the application needs.
Application Manifest Schema
Application manifests are not new to the Windows Vista release. Manifests were used in Windows XP to help application developers identify such things as which versions of DLLs the application was tested with. Providing the execution level is an extension to that existing application manifest schema.
The Windows Vista application manifest has been enhanced with attributes that permit developers to mark their applications with a requested execution level. The following is the format for this:
<requestedExecutionLevel
level="asInvoker|highestAvailable|requireAdministrator"
uiAccess="true|false"/>
Requested Execution Levels
Possible requested execution level values
Value |
Description |
Comment |
|---|---|---|
asInvoker |
The application runs with the same access token as the parent process. |
Recommended for standard user applications. Do refractoring with internal elevation points, as per the guidance provided earlier in this document. |
highestAvailable |
The application runs with the highest privileges the current user can obtain. |
Recommended for mixed-mode applications. Plan to refractor the application in a future release. |
requireAdministrator |
The application runs only for administrators and requires that the application be launched with the full access token of an administrator. |
Recommended for administrator only applications. Internal elevation points are not needed. The application is already running elevated. |
Note
Hosting applications can become standard user or administrator-only applications only if they support that certain type of hosted application. For example, MMC.exe now only hosts administrative snap-ins, and Explorer.exe only hosts standard user code.
System behavior
Application Marking |
Virtualize? |
|---|---|
Unmarked |
Yes |
asInvoker |
No |
requireAdministrator |
No |
highestAvailable |
No |
Application Manifest Marking and Application Launch Behavior
This section details the behavior of the elevation prompt depending on the parent process access token, the setting for the User Account Control: Behavior of the elevation prompt for administrators in Admin Approval Mode policy and the User Account Control: Behavior of the elevation prompt for standard users policy, and the requested execution level marking for the application.
Whether an application can run and which user rights and administrative Windows privileges it can obtain are dependent upon the combination of the application’s requested execution level in the application compatibility database and the administrative privileges available to the user account that launched the application. The following tables identify the possible run-time behavior based on such possible combinations.
Application launch behavior for a member of the local Administrators group
Parent Process Access Token |
Consent Policy for Members of the Local Administrators Group |
None or asInvoker |
highestAvailable |
requireAdministrator |
|---|---|---|---|---|
Standard user |
No prompt |
Application launches as a standard user |
Application launches with a full administrative access token; no prompt |
Application launches with a full administrative access token; no prompt |
Standard user |
Prompt for consent |
Application launches as a standard user |
Application launches with a full administrative access token; prompt for consent |
Application launches with a full administrative access token; prompt for consent |
Standard user |
Prompt for credentials |
Application launches as a standard user |
Application launches with a full administrative access token; prompt for credentials |
Application launches with a full administrative access token; prompt for credentials |
Administrator (UAC is disabled) |
NA |
Application launches with a full administrative access token; no prompt |
Application launches with a full administrative access token; no prompt |
Application launches with a full administrative access token; no prompt |
Application launch behavior for a standard user account
Parent Process Access Token |
Consent Policy for Standard Users |
asInvoker |
highestAvailable |
requireAdministrator |
|---|---|---|---|---|
Standard user |
No prompt |
Application launches as a standard user |
Application launches as a standard user |
Application fails to launch |
Standard user |
Prompt for credentials |
Application launches as a standard user |
Application launches as a standard user |
Prompt for administrator credentials before running application |
Standard user (UAC is disabled) |
NA |
Application launches as a standard user |
Application launches as a standard user |
Application might launch but will fail later |
Application launch behavior for a standard user with additional privileges (e.g., Backup Operator)
Parent Process Access Token |
Consent Policy for Standard Users |
asInvoker |
highestAvailable |
requireAdministrator |
|---|---|---|---|---|
Standard user |
No Prompt |
Application launches as a standard user |
Application launches as a standard user with additional privileges |
Application fails to launch |
Standard user |
Prompt for credentials |
Application launches as a standard user |
Prompt for credentials before running the application |
Prompt for administrator credentials before running application |
Standard user (UAC is disabled) |
NA |
Application launches as a standard user |
Application launches as a standard user with additional privileges |
Application might launch but will fail later |
uiAccess Values
Possible uiAccess values
Value |
Description |
|---|---|
False |
The application does not need to drive input to the user interface of another window on the desktop. Applications that are not providing accessibility should set this flag to false. Applications that are required to drive input to other windows on the desktop (on-screen keyboard, for example) should set this value to true. |
True |
The application is allowed to bypass user interface control levels to drive input to higher privilege windows on the desktop. This setting should only be used for user interface Assistive Technology applications. |
Important
Applications with the uiAccess flag set to true must be Authenticode signed to start properly. In addition, the application must reside in a protected location in the file system. \Program Files\ and \windows\system32\ are currently the two allowable protected locations.
How to Create an Embedded Manifest with Microsoft Visual Studio®
Visual Studio® provides the capability to automatically embed an XML application manifest file within the resource section of the Portable Executable (PE) image. This section addresses how to use Visual Studio to create a signed PE image containing an application manifest. This application manifest can therefore include the necessary requestedExecutionLevel attributes, allowing the application to run with the desired privilege level on Windows Vista. When the program is launched, the application manifest information will be extracted from the resource section of the PE and used by the operating system. It is not necessary to use the Visual Studio graphical user interface (GUI) to include a manifest. Once the necessary changes are in the source code, compiling and linking using command-line tools will also include the application manifest in the resulting PE image.
Manifest File
To mark your application with a requestedExecutionLevel, first create an application manifest file to use with the target application. This file can be created by using any text editor. The application manifest file should have the same name as the target executable file with a .manifest extension. For example: IsUserAdmin.exe.manifest.
Example
Executable: IsUserAdmin.exe
Manifest:IsUserAdmin.exe.manifest
Sample application manifest file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<assemblyIdentity version="1.0.0.0"
processorArchitecture="X86"
name="IsUserAdmin"
type="win32"/>
<description>Description of your application</description>
<!-- Identify the application security requirements. -->
<trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
<security>
<requestedPrivileges>
<requestedExecutionLevel
level="requireAdministrator"
uiAccess="false"/>
</requestedPrivileges>
</security>
</trustInfo>
</assembly>
The parts of the manifest that need to be adjusted for your application are marked in bold. They include the following:
The assembly identity
The name
The type
The description
The attributes in the requestedExecutionLevel
Building Application Manifests Within C/C++ Code with Visual Studio® 2005 for Windows Vista-Only Applications
Important
If your application is intended to run on both Windows Vista and Windows XP, you must follow the procedures detailed in the next section: Building and Embedding an Application Manifest with Microsoft Visual Studio 2005 for Windows XP and Windows Vista Applications.
Next, you have to attach the application manifest to the executable by adding a line in the resource file of the application (the .rc file) to have Microsoft Visual Studio embed your manifest within the resource section of the PE file. To accomplish this, place the application manifest in the same directory as the source code for the project you are building and edit the resource file to include the following lines:
#define MANIFEST_RESOURCE_ID 1
MANIFEST_RESOURCE_ID RT_MANIFEST "IsUserAdmin.exe.manifest"
Replace IsUserAdmin.exe.manifest with the name of your application's manifest. After rebuilding the application, the application manifest should be embedded in the resource section of the executable.
Building and Embedding a Manifest with Microsoft Visual Studio® 2005 for Windows XP and Windows Vista Applications
In Visual Studio 2005, the C/C++ integrated development environment (IDE) interface that permits the inclusion of additional manifest files in a target executable file does some processing on the XML, which inserts a duplicate xmlns tag. Because of this, the previously documented method on how to include an application manifest in a Visual Studio 2005 C++ project cannot be used if the application should run on both Windows Vista and Windows XP. The following procedures are modified to include explicit version tags in the trustInfo section.
A fix is planned for the mt.exe tool to address the problem where it generates the duplicate namespace declaration in the XML. Until a new version of mt.exe is available, you can avoid the problem of merging application manifests by explicitly adding in version tags into the trustinfo section of the manifest. A sample application manifest is shown below:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<ms_asmv2:trustInfo xmlns:ms_asmv2="urn:schemas-microsoft-
com:asm.v2">
<ms_asmv2:security>
<ms_asmv2:requestedPrivileges>
<ms_asmv2:requestedExecutionLevel level="asInvoker">
</ms_asmv2:requestedExecutionLevel>
</ms_asmv2:requestedPrivileges>
</ms_asmv2:security>
</ms_asmv2:trustInfo>
</assembly>
C or C++ Project
The following procedure details how to create an application manifest for a C or C++ project type in Visual Studio 2005.
To create a manifest for a C or C++ project in Microsoft Visual Studio 2005
Open your project in Microsoft Visual Studio 2005.
Under Project, select Properties.
In Properties, select Manifest Tool, and then select Input and Output.
Add in the name of your application manifest file under Additional manifest files.
Rebuild your application.
Note The updated manifests that include explicit version tags will permit the application to run correctly on both Windows Vista and Windows XP.
Managed Code (C#, J# and Visual Basic)
Visual Studio does not currently embed a default application manifest into managed code. For managed code, the developer should insert a default application manifest into the target executable using mt.exe. The following procedure details this process.
To insert a default manifest file into the target executable with mt.exe
Use a text editor, such as Windows Notepad, to create a default manifest file, temp.manifest.
Use mt.exe to insert the manifest. The command would be: mt.exe –manifest temp.manifest –outputresource:YourApp.exe;#1.
Adding the Application Manifest as a Step in Visual Studio Post-Build
Adding the application manifest can be automated as a post-build step as well. This option is available for C/C++ and for the two managed code languages of C# and J#.
Note
The IDE does not currently include a post-build option for a Visual Basic application.
To automate the addition of the application manifest as a post-build step, place the following line as a post build task in your Visual Studio project's Project Properties:
mt.exe -manifest "$(ProjectDir)$(TargetName).exe.manifest" -updateresource:"$(TargetDir)$(TargetName).exe;#1"