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 Note:
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 Note:
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"

Concepts

Designing UAC Applications for Windows Vista