Sign an MSIX package with Device Guard signing

Device Guard signing is a Device Guard feature that is available in the Microsoft Store for Business and Education. It enables enterprises to guarantee that every app comes from a trusted source. Starting in Windows 10 Insider Preview Build 18945, you can use SignTool in the Windows SDK to sign your MSIX apps with Device Guard signing. This feature support enables you to easily incorporate Device Guard signing into the MSIX package building and signing workflow.

Device Guard signing requires permissions in the Microsoft Store for Business and uses Azure Active Directory (AD) authentication. To sign an MSIX package with Device Guard signing, follow these steps.

  1. If you haven't done so already, sign up for Microsoft Store for Business or Microsoft Store for Education.

    Note

    You only need to use this portal to configure permissions for Device Guard signing.

  2. In the Microsoft Store for Business (or or Microsoft Store for Education), assign yourself a role with permissions necessary to perform Device Guard signing.
  3. Register your app in the Azure portal with the proper settings so that you can use Azure AD authentication with the Microsoft Store for Business.
  4. Get an Azure AD access token in JSON format.
  5. Run SignTool to sign your MSIX package with Device Guard signing, and pass the Azure AD access token you obtained in the previous step.

The following sections describes these steps in more detail.

Configure permissions for Device Guard signing

To use Device Guard signing in the Microsoft Store for Business or Microsoft Store for Education, you need the Device Guard signer role. This is the least privilege role that has the ability to sign. Other roles such as Global Administrator and Billing account owner can also sign.

To confirm or reassign roles:

  1. Sign in to the Microsoft Store for Business.
  2. Select Manage and then select Permissions.
  3. View Roles.

For more information, see Roles and permissions in the Microsoft Store for Business and Education.

Register your app in the Azure Portal

To register your app with the proper settings so that you can use Azure AD authentication with the Microsoft Store for Business:

  1. Sign in to the Azure portal and follow the instructions in Quickstart: Register an application with the Microsoft identity platform to register the app that will use Device Guard signing.

    Note

    Under Redirect URI section, we recommend you choose Public client (mobile & desktop). Otherwise, if you choose Web for the app type, you will need to provide a client secret when you obtain an Azure AD access token later in this process.

  2. After you register your app, on the main page for your app in the Azure portal, click API permissions and add a permission for the Windows Store for Business API.

  3. Next, select Delegated permissions and then select user_impersonation.

Get an Azure AD access token

Next, obtain an Azure AD access token for your Azure AD app in JSON format. You can do this using a variety of programming and scripting languages. For more information about this process, see Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow. We recommend that you retrieve a refresh token along with the access token, because your access token will expire in one hour.

Note

If you registered your app as a Web app in the Azure portal, you must provide a client secret when you request your token. For more information, see the previous section.

The following PowerShell example demonstrates how to request an access token.

function GetToken()
{

    $c = Get-Credential -Credential $user
    
    $Credentials = New-Object System.Management.Automation.PSCredential -ArgumentList $c.UserName, $c.password
    $user = $Credentials.UserName
    $password = $Credentials.GetNetworkCredential().Password
    
    $tokenCache = "outfile.json"

    #replace <application-id> and <client_secret-id> with the Application ID from your Azure AD application registration
    $Body = @{
      'grant_type' = 'password'
      'client_id'= '<application-id>'
      'resource' = 'https://onestore.microsoft.com'
      'username' = $user
      'password' = $password
    }

    $webpage = Invoke-WebRequest 'https://login.microsoftonline.com/common/oauth2/token' -Method 'POST'  -Body $Body -UseBasicParsing
    $webpage.Content | Out-File $tokenCache -Encoding ascii
}

Note

We recommand that you save your JSON file for later use.

Sign your package

After you have your Azure AD access token, you are ready to use SignTool to sign your package with Device Guard signing. For more information about using SignTool to sign packages, see Sign an app package using SignTool.

The following command line example demonstrates how to sign a package with Device Guard signing.

signtool sign /fd sha256 /dlib DgssLib.dll /dmdf <Azure AAD in .json format> /t <timestamp-service-url> <your .msix package>

Note

  • We recommend that you use one of the timestamp options when you sign your package. If you do not apply a timestamp, the signing will expire in one year and the app will need to be resigned.
  • Make sure that the publisher name in your package's manifest matches the certificate you are using to sign the package. With this feature, it will be your leaf certificate. For example, if leaf certificate is CompanyName, than the publisher name in the manifest must be CN=CompanyName. Otherwise, the signing operation will fail.
  • Only the SHA256 algorithm is supported.
  • When you sign your package with Device Guard signing, your package is not being sent over the Internet.

Test

To test the Device Guard signing, download your organziation's root certificate from the Microsoft Store for Business Portal.

  1. Sign in to the Microsoft Store for Business.
  2. Select Manage and then select Settings.
  3. View Devices.
  4. View Download your organization's root certificate for use with Device Guard
  5. Click Download

Deploy this certificate to your device. Install your newly signed app to verify that you have successfully signed your app with Device Guard signing.

Common errors

Here are common errors you might encounter.

  • 0x800700d: This common error means that the format of the Azure AD JSON file is invalid.