Document staging ACLs for manual staging (AB#21705401)

msix-src/desktop/deploy-preinstalled-apps.md

@@ -1,7 +1,7 @@
 ---
 title: Preinstalling packaged apps 
 description: This article provides an overview of preinstalled apps 
-ms.date: 11/30/2020
+ms.date: 07/18/2026
 ms.topic: how-to
 author: andreww-msft
 ms.author: jken
@@ -30,6 +30,76 @@ The staging of a packaged app can be performed on an offline image (.wim, .vhd,
 ### Registration
 After a packaged app has been staged, the app can then be registered to users on the device. Registration occurs on a per-user basis, and begins when a user of the device logs on. The operating system will then load the preinstalled packaged app package creating user specific app data, create file type associations, and app tiles in the start menu. This accomplished by the App Rediness Service (ARS) which is aware of all pre-installed apps. 
 
+## Staging permissions (ACLs)
+
+When you stage a packaged app with a provisioning tool such as DISM or
+[Add-AppxProvisionedPackage](/powershell/module/dism/add-appxprovisionedpackage?preserve-view=true),
+the tool sets the correct file system permissions
+([ACLs](/windows/win32/secauthz/access-control-lists)) on the staged files for you. When you stage
+packages manually - for example, to an external volume, a network share, or a staging directory that
+remote or virtual desktops mount - the same ACLs still need to be set.
+
+Whether you set the ACLs, or Windows deployment sets them, depends on how the staging location is
+mounted:
+
+- If the location is mounted read-only, deployment can't update the ACLs, so you must set them
+  yourself before staging.
+- If the location is mounted read-write by the `LocalSystem` account, deployment can set the ACLs
+  for you, but at a one-time performance cost. Set the ACLs in advance to avoid that cost.
+
+Either way, if the required ACLs are missing, registration can fail, or registration succeeds but
+the packaged process fails to launch at runtime because it can't read its own files.
+
+> [!NOTE]
+> The principals listed below are the identities that the deployment runtime and the packaged
+> app container rely on. Confirm them against your environment and grant only the least privilege
+> required before deploying broadly.
+
+### Local or external staging volume
+
+Grant the following on the staging folder and everything it contains so that any user on the device
+can register and run the app:
+
+| Principal | SID | Access |
+|-----------|-----|--------|
+| `SYSTEM` | `S-1-5-18` | Full control |
+| `Administrators` | `S-1-5-32-544` | Full control |
+| `Users` | `S-1-5-32-545` | Read & execute |
+| `ALL APPLICATION PACKAGES` | `S-1-15-2-1` | Read & execute |
+| `ALL RESTRICTED APPLICATION PACKAGES` | `S-1-15-2-2` | Read & execute |
+
+The `ALL APPLICATION PACKAGES` and `ALL RESTRICTED APPLICATION PACKAGES` entries are needed because
+packaged processes can run in an app container. These access control entries
+([ACEs](/windows/win32/secauthz/access-control-entries)) ensure that those processes can access the
+staged files. If these processes lack this access, they fail to launch at runtime.
+
+Apply the permissions with `icacls`, using the SIDs so the command works regardless of display
+language:
+
+```cmd
+icacls "D:\MsixStaging" /grant "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-32-545:(OI)(CI)RX" "*S-1-15-2-1:(OI)(CI)RX" "*S-1-15-2-2:(OI)(CI)RX"
+```
+
+### Network share or virtual desktop staging directory
+
+When packages are staged to an SMB file share that remote or virtual desktops mount during sign-in -
+for example, a Windows Virtual Desktop or Azure Virtual Desktop staging directory - each session
+host reads the staged files as its *computer account*. Grant **Read and eXecute** to each session
+host computer object, or, for easier management, to an Active Directory security group that contains
+those computer accounts, on both:
+
+- the staged files and folders
+- the file share
+
+```cmd
+icacls "\\server\share\MsixImages" /grant "CONTOSO\AVD-SessionHosts$:(OI)(CI)RX"
+```
+
+For Azure Files and the Azure role-based access control (RBAC) roles required when you use App
+Attach with Azure Virtual Desktop, see
+[App attach in Azure Virtual Desktop](/azure/virtual-desktop/app-attach-overview#file-share) and
+[Set up App Attach](/azure/virtual-desktop/app-attach-setup).
+
 ## DISM
 DISM is a command-line tool that can be used to service and prepare Windows images, including those used for Windows Pre-Execution (Win-PE), Recovery Environment (Win-RE), and Windows Setup. Dism can be used to service a Windows image (.wim) or virtual hard disks (.vhd, or .vhdx).
 

msix-src/desktop/register-from-network.md

@@ -1,7 +1,7 @@
 ---
 description: This article provides guidance on how to register a package layout from a network share
 title: Registering a package layout from a network share
-ms.date: 02/06/2020
+ms.date: 07/18/2026
 ms.topic: how-to
 keywords: windows 10, uwp, msix
 ms.assetid: f45d8b14-02d1-42e1-98df-6c03ce397fd3
@@ -21,7 +21,9 @@ Multiple people can contribute to a single app package layout on a network share
 
 3. Collaborators will need read and write access to the build folder.
 
-4. Users will only need to read access to the build folder.
+4. Users will only need read access to the build folder.
+
+5. Packaged processes can run in an app container, so the build folder must also grant **Read and eXecute** to the app-container identities `ALL APPLICATION PACKAGES` (`S-1-15-2-1`) and `ALL RESTRICTED APPLICATION PACKAGES` (`S-1-15-2-2`). These [access control entries](/windows/win32/secauthz/access-control-entries) let the packaged processes access their files from the share; without them, registration can succeed but the processes fail to launch at runtime. For the full set of staging permissions and `icacls` examples, see [Staging permissions (ACLs)](deploy-preinstalled-apps.md#staging-permissions-acls).
 
 ## In Visual Studio
 

msix-src/msix-troubleshooting-guide.md

@@ -1,7 +1,7 @@
 ---
 description: Solutions for the most common MSIX installation, signing, deployment, and runtime errors on Windows 10 and Windows 11.
 title: MSIX troubleshooting guide
-ms.date: 04/14/2026
+ms.date: 07/02/2026
 ms.topic: troubleshooting-general
 author: GrantMeStrength
 ms.author: jken
@@ -33,7 +33,7 @@ For a full log of deployment events, open Event Viewer and navigate to:
 | Running as a standard user without elevation when the package requires per-machine install | Run PowerShell as Administrator. To install for all users, use `Add-AppxProvisionedPackage` instead of `Add-AppxPackage`. |
 | Antivirus or security software blocking the package file | Temporarily disable real-time scanning, or add an exclusion for the `.msix` / `.msixbundle` file |
 | Package staged for another user and not provisioned | Use `Add-AppxProvisionedPackage` to provision for all users |
-| File system ACLs blocking read access to the package | Check permissions on the package file with `icacls`; grant read access to the installing user |
+| File system ACLs blocking read access to the package | Check permissions on the package file with `icacls`; grant read access to the installing user. For packages staged manually to a volume or file share, also grant read to the app-container identities — see [Staging permissions (ACLs)](desktop/deploy-preinstalled-apps.md#staging-permissions-acls) |
 
 ### Package installation blocked because the app is in use