App Elevation Samples – Part 3

Picture5

If you haven’t read part 1 and part 2 of this series yet, please start there first. I have covered the “hello world” version of a packaged app that requires elevation at launch time and showed how a packaged app can dynamically elevate itself. In this post we’ll get to the fun part: using the ‘allowElevation’ capability from a UWP app to execute code with elevated privileges on Windows 10 desktop with the 1809 update.

TL;DR

I already have the 1809 update and the Windows SDK 17763 (or later) installed. Just show me the code on GitHub …

Sample Code Repo on Github

Step-by-Step Tutorial

1. Create a new Universal Windows App

Make sure you run Windows 10 with the 1809 update and have the Windows SDK 17763 (or later) installed. Now create a new C# Universal Windows application in Visual Studio 2017 (can use any supported programming language as well, e.g. C++, JS, …):

FileNewProject2

Be sure to set both “Minimum” and “Target” version to 17763 or higher as build number 17763 maps to the 1809 update for Windows 10. The ‘allowElevation’ capability we will be using has been introduced in 1809 and is not available in earlier versions of Windows 10.

setVersions

Now we need to add a ‘fullTrustProcess’ desktop extension to our UWP that will contain the code we want to run with elevated privileges. For a complete tutorial on UWP desktop extension read up here on all the details. In this post I will quickly move through the steps of setting up the desktop extension for our new UWP app:

2. Add the desktop extension project

For this example we want the desktop extension process to be headless (i.e. a background process without UI). It can have a UI as well if that’s what you need for your scenario. So let’s add a C# desktop console application (of course this could be C++, VB, etc. as well) and call it “Elevated Extension”:

addConsole2We don’t want a console box to pop up for our elevated background process, so we need to configure this project to run headless. For that go into the project settings and change the Output Type from “Console Application” to “Windows Application” (I know, not very intuitive …)

outputType

5. Packaging everything together

Next we need to add a “Windows Application Packaging Project” (look for it in the “Windows Universal” category). Name it “Package” and make it the startup project,  so your solution setup looks like in the screenshot below. In order to package both the UWP and the desktop code in one app package, add both as Application references to the Packaging project:

addref3

6. Configuring the appx manifest

Now to connect the two projects we need to declare the “fullTrustProcess” desktop extension in the package manifest. For this open the Package.appxmanifest file in the Packaging project (“Package”) in XML editing mode and add the extension within the <Application> node. While we are in this file we are also adding the “appExecutionAlias” extension that we learned about in part 2, as we will need it to launch our extension with elevated privileges. Last but not least, you will also need to add namespace definitions for “uap3” and “desktop” in the root <Package> element per below snippet.

<Package
  ...
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  IgnorableNamespaces="uap3 desktop ...">
  ...

  <Extensions>

    <desktop:Extension Category="windows.fullTrustProcess"
                       Executable="Elevated Extension\Elevated Extension.exe">
      <desktop:FullTrustProcess>
        <desktop:ParameterGroup GroupId="User" Parameters="/user" />
        <desktop:ParameterGroup GroupId="Admin" Parameters="/admin" />
      </desktop:FullTrustProcess>
    </desktop:Extension>

    <uap3:Extension Category="windows.appExecutionAlias"
                    Executable="Elevated Extension\Elevated Extension.exe"
                    EntryPoint="Windows.FullTrustApplication">
      <uap3:AppExecutionAlias>
        <desktop:ExecutionAlias Alias="ElevatedExtension.exe" />
      </uap3:AppExecutionAlias>
    </uap3:Extension>

  </Extensions> 
  ...
</Package>

Note that the the two parameter groups I am defining for the desktop extension are not mandatory. I am doing it here only for this sample to later demonstrate how we can launch the extension with either user privileges or admin privileges.

7. Adding the launcher code

Now that solution and manifest are set up and configured correctly, we are ready to add the code to launch the extension from the UWP – as either elevated or regular process. First lets add some XAML to MainPage.xaml:

<StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
    <Button Content="Run Backgroundprocess as User"
            Click="ButtonUser_Click"
            HorizontalAlignment="Stretch"
            FontSize="32" Margin="3"/>
    <Button Content="Run Backgroundprocess as Admin"
            Click="ButtonAdmin_Click"
            HorizontalAlignment="Stretch"
            FontSize="32" Margin="3"/>
</StackPanel>

Before we can add the code-behind for the button click handlers, we need to add a reference to the UWP desktop extension SDK, because that’s where the FullTrustProcessLauncher API is defined. This API, btw, is not new in the 1809 update. It has been around since the Creators Update (SDK build 14393), but it’s recommended you reference the Desktop extension SDK that matches your target version, i.e. 17763 in our case.

addDeskExte

Next we add the two button click handlers in MainPage.xaml.cs. The key piece is the FullTrustProcessLauncher API. We are passing in the parametergroup to indicate to the extension whether we need to run it as user or with admin privileges. The processing of this parameter is application logic as we will see in the next step. Wrapping this call into an “IsApiContractPresent” is an important practice to ensure our universal app can run without crashing also on non-desktop devices that don’t support the FullTrustProcessLauncher API:

private async void ButtonUser_Click(object sender, RoutedEventArgs e)
{
  if (ApiInformation.IsApiContractPresent(
      "Windows.ApplicationModel.FullTrustAppContract", 1, 0))
  {
    await
      FullTrustProcessLauncher.LaunchFullTrustProcessForCurrentAppAsync("User");
  }
}

private async void ButtonAdmin_Click(object sender, RoutedEventArgs e)
{
  if (ApiInformation.IsApiContractPresent(
      "Windows.ApplicationModel.FullTrustAppContract", 1, 0))
  {
    await
      FullTrustProcessLauncher.LaunchFullTrustProcessForCurrentAppAsync("Admin");
  }
}

The final piece of code we need to add now goes into Program.cs of the “Elevated Extension” project. This is the code that handles the “/user” vs “/admin” parameter. If the latter has been specified we want to do the same as in part 2, i.e. relaunch the process as admin using the AppExecutionAlias. In case you are wondering why the strings we are handling here are different from the strings being passed to the launch API (“/user vs “User”), take a look at the ParameterGroup entries we added to the manifest. It maps a friendly name (“User”) to what could be in some case a fairly convoluted long string of parameters (“/user” in our case).

static void Main(string[] args)
{
    if (args.Length > 2)
    {
        if (args[2] == "/admin")
        {
          string aliasPath =
      Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData) +
      @"\microsoft\windowsapps\ElevatedExtension.exe";

          ProcessStartInfo info = new ProcessStartInfo();
          info.Verb = "runas";
          info.UseShellExecute = true;
          info.FileName = aliasPath ;
          Process.Start(info);
          return;
        }
    }

    AutoResetEvent areWeDone = new AutoResetEvent(false);
    // do some task, then exit
    areWeDone.WaitOne(10000); 
}

8. Run and test the solution

Now we are ready to run and test our solution, before hitting F5 make sure the “Package” project is set as startup project and you have added the “allowElevation” capability in its appx manifest:

  <Capabilities>
    <Capability Name="internetClient" />
    <rescap:Capability Name="runFullTrust" />
    <rescap:Capability Name="allowElevation" />
  </Capabilities>

When the UWP is up-and-running use the buttons to launch the extension either as user or as admin. Observe the result in TaskManager, remember that the extension has been coded to exit itself after 10sec in this example:

uwpElevated

This concludes my 3-part tutorial about the new ‘allowElevation’ capability. Please leave your feedback and questions as comments and I will do my best to address them in a timely fashion.

Picture0

Advertisements

29 thoughts on “App Elevation Samples – Part 3

  1. Hi Stefan.

    I’ve also been reading your other article on “UWP WITH DESKTOP EXTENSION ”
    https://stefanwick.com/2018/04/06/uwp-with-desktop-extension-part-2/

    I wanted to implement something like scenario 2 so that I can use the launcher program to pass parameters (ip addresses) to netsh and perform ip properties changes to the system. Does that mean i need to self-elevate the launcher program or netsh, or both?

    If it’s just the launcher program that needs elevation, which you have demonstrated in this article, how do i launch netsh after that? Do I start a new netsh process after AutoResetEvent?

    If it’s just the netsh that needs elevation, does that mean at package manifest, I’d set AppExecutionAlias I to point that the full path of netsh?

    Thanks.

    Like

    1. You can’t point directly to netsh (or other EXEs outside your package) in the appx manifest. To solve it you can include a tiny EXE (like my Launcher.exe) as “windows.fullTrustProcess” extension in your UWP package and launch it via FullTrustProcessLauncher. This process will then run outside of the sandbox and you can launch netsh (or any other EXE on your system) from there. To launch it as elevated process follow the steps from the other post.

      Like

  2. Thanks Stefan, got it working now. It didn’t work before because when I was going through part 1 of this sample, I added application manifest for the win32 application, but forgot to remove it when doing self-elevation, as you pointed out in part 2.

    Like

  3. Hi Stefan, I’m also trying to get UWP to receive response from the launched process, which is similar to your other article: https://stefanwick.com/2018/04/16/uwp-with-desktop-extension-part-3/ where AppService connection is used to pass request and response between both sides.

    However the method described in this article pass request (as parameter) through fullTrustProcess instead. So how would we handle sending the response from process back to UWP?

    Like

    1. With elevated processes this is unfortunately more tricky. Would be a worth a blog post of its own. An elevated process can’t connect to a UWP app process, so you would have to use a different communication mechanism. In a simple case you may be able to just do file-based communincation, or you have a non-elevated Win32 process in between your UWP and the elevated process.

      Like

      1. Hi Stephan, Thank you so much for the post. It was really helpful. As you mentioned above, communication between UWP process and launched elevated process is more tricky. I need exactly the same thing for my project. Have you already written a blog on this? If not, do you have any plans to do so?

        Like

      2. Hi Sanjay, I don’t have a blog post on this yet (and not aware of other docs covering it). It’s still a very new feature (technically the 1809 update hasn’t fully been released yet). I have moved on to a different team in Microsoft by now, but I will check with the team to see if there is any guidance documentation coming out for this soon. Thanks for the question/feedback!

        Like

  4. Hello Stefan,

    “I will check with the team to see if there is any guidance documentation coming out for this soon”

    Is there any update on this from the team?

    Like

    1. Nothing concrete to share yet. AppService support for this scenario is being investigated for a future update. For now you’d have to come up with your own way to communicate. Depending on your scenario I guess you could exchange information via files, or put a non-elevated Win32 process in between your elevated process and the UWP to proxy the communication.

      Like

      1. Thanks Stefan for the update! I will be really great if you could update me once AppService way is available in future release. For now I will rely on File based IO.

        Thanks,
        Sanjay

        Like

  5. Hi Stefan,
    Thanks for sharing this post. I have two questions:
    1. With this approach, can we set values in the registry( HKEY_LOCAL_MACHINE).
    2. I currently on windows 10 sdk 14393.0 and I facing issues while running win32 process having administrative privileges. Is upgrading to Windows SDK 17763 only option.
    Thanks

    Like

  6. Thanks Stefan. So with this approach mentioned in this blog ( using Windows SDK 17763), does it allow us write into the registry(HKEY_LOCAL_MACHINE) from the win32 background process.

    Like

      1. Thanks for answering my queries. I’ll explore the steps you have mentioned in the blog
        I might be digressing here, but I didn’t find any way to launch UWP as administrator( I am still going through the documentation). Is there any recommended way that you suggest me. It would be helpful.

        Like

  7. To summarize, In order for UWP to launch an elevated win32, I have follow the steps mentioned in your blog. This would need Windows SDK 17763. We’ll not be able to achieve this on older SDKs like 14393. Please let me know if my understanding is right.

    Thanks again for your time!

    Like

  8. Hi Stefan,

    Similar to what you have explained in the blog above, I have one existing win32 app, which I want to launch with elevated access from UWP app via normal launcher fulltrust process. I am not able to launch this win32 App because it has some dependency on win32 Dlls, If I include all these additional DLLS using static library, then I am able to launch win32 exe in elevated mode. Just to summarize, below are two scenarios:

    CASE 1: (Working case)

    UWP App ==> Launches Fulltrust process ==> launches my win32 exe (having NO DLL dependency) in elevated mode

    CASE 2: (Failure Case)

    UWP App ==> Launches Fulltrust process ==> Fails to launch EXE (having DLL dependency) in elevated mode

    Can you please confirm whether this is a limitation ( or as designed) on Win10 RS5 or I am doing something wrong?

    Thanks,
    Sanjay

    Like

    1. Are those additional DLLs part if the operating system, or part of an app. If the latter you will need to include them in the package, because otherwise the package wouldn’t work when installed on another system. This isn’t specific to elevation. You shouldn’t have to link them statically though.

      Like

  9. Hi Stefan,

    Thanks for the quick reply. These dlls are part of win32 App which needs to run in elevated mode. As there are three versions of dlls (x86, x64 and ARM), can you please suggest how do I do it or provide any pointer/msdn link which explains how to do this.

    I tried to add them in Packaging project along with Applications thinking that visual studio will take care of adding them in the package along with other win32/uwp applications, but VS does not allow us to select/add any projects which do not produce an executable.

    Thanks,
    Sanjay

    Like

  10. Hi Stefan,

    I am not sure at this point of time. It would be great if you could provide some reference on both of the approaches.

    Actually my solution structure is something like below.

    1) UWP App (e.g SampleUWPClientApp)
    2) UWP library (e.g Sample SampleUWPLibrary which is referenced by SampleUWPClientApp)
    3) RunFullTrust Win32 Exe (e.g SampleDesktopExtension, which loads few DLLs dynamically using LoadLibrary). This will be launched from my UWP library (SampleUWPLibrary )
    4) VS UWP Packaging project (e.g Package, Currently this includes 1 and 2 in applications as a reference and 3 as part of manifest desktop extension)

    I am working on developing 2) and 3) whereas 1 and 4 are done by someone else. Is it possible to just share the binaries (e.g Nuget package which includes both UWP dll and win32 Extension along with Win32 DLLS) or some some other mechanism to have it integrated with 1 and 4)

    Thank you so much for all the help and support.

    Thanks,
    Sanjay

    Like

      1. Thank you so much Stefan! This was very helpful information. I was able to load DLLs from my win32 exe. I really appreciate all the help you provided to me.

        Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s