Document staging ACLs for manual staging (AB#21705401) by RDMacLachlan · Pull Request #474 · MicrosoftDocs/msix-docs

RDMacLachlan · 2026-07-02T16:20:34Z

Summary

Resolves AB#21705401 — [MSIX Docs] Document ACLs required for staging for people who don't want to run the tool.

The bug asked us to document the ACLs (file system permissions) required on a WVD/external staging directory for admins who stage MSIX packages manually, rather than relying on a provisioning tool to set permissions. That guidance did not exist anywhere in the docs.

Changes

desktop/deploy-preinstalled-apps.md — New Staging permissions (ACLs) section:
- Local/external staging volume: SYSTEM, Administrators, Users, ALL APPLICATION PACKAGES (S-1-15-2-1), ALL RESTRICTED APPLICATION PACKAGES (S-1-15-2-2), with an icacls example. Explains why the app-container SIDs are required (app fails to launch without them even if registration succeeds).
- Network share / virtual desktop (WVD/AVD) staging directory: grant each session-host computer account (or an AD group) Read & execute on both NTFS and SMB, with an icacls example and links to the AVD App Attach docs.
desktop/register-from-network.md — Prerequisites now call out the app-container SIDs the share must grant read to, linking to the new section.
msix-troubleshooting-guide.md — The ACL troubleshooting row now points to the new staging permissions guidance.

Notes for reviewers

The exact per-machine ACL identities should be confirmed with the App Deployment team before publishing; the values here reflect the standard WindowsApps/app-container permission set.

Adds guidance on the file system permissions (ACLs) required when staging MSIX packages manually - to a local/external volume, a network share, or a WVD/AVD staging directory - rather than relying on a provisioning tool to set them. - deploy-preinstalled-apps.md: new "Staging permissions (ACLs)" section covering local/external volumes (SYSTEM, Administrators, Users, ALL APPLICATION PACKAGES, ALL RESTRICTED APPLICATION PACKAGES) and network/ virtual-desktop shares (session-host computer accounts on NTFS + SMB), with icacls examples and links to AVD App Attach docs. - register-from-network.md: call out the app-container SIDs the share must grant read to, linking to the new section. - msix-troubleshooting-guide.md: point the ACL troubleshooting row at the new staging permissions guidance. Resolves AB#21705401 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

learn-build-service-prod · 2026-07-02T16:21:31Z

Learn Build status updates of commit 9b5ce28:

✅ Validation status: passed

File	Status	Preview URL	Details
msix-src/desktop/deploy-preinstalled-apps.md	✅Succeeded
msix-src/desktop/register-from-network.md	✅Succeeded
msix-src/msix-troubleshooting-guide.md	✅Succeeded

For more details, please refer to the build report.

RDMacLachlan · 2026-07-02T16:36:40Z

@DrusTheAxe - Please review content.

DrusTheAxe · 2026-07-06T17:08:39Z


+## 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) on the staged files for you. If you stage packages *manually* — for example, to an external volume, a network share, or a staging directory that remote or virtual desktops mount — you must set these ACLs yourself. Without them, registration can fail, or registration succeeds but the app fails to launch because the packaged process can't read its own files.


RECOMMEND: .md max line length = 100

(vscode with that extension make it suuuupereasy to reflow properly)

DrusTheAxe · 2026-07-06T17:12:07Z


+## 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) on the staged files for you. If you stage packages *manually* — for example, to an external volume, a network share, or a staging directory that remote or virtual desktops mount — you must set these ACLs yourself. Without them, registration can fail, or registration succeeds but the app fails to launch because the packaged process can't read its own files.


YOU don't need to set them.
They NEED to be set. If you don't set them Deployment will - if we can.

If you mount the external/net/etc volume as READONLY then Deployment CAN'T update ACLs - you must set it.

If you mount the external/net/etc volume as READWRITE by LocalSystem then Deployment CAN update ACLs, but there's a (one-time) performance cost. You can optimize this by seting the ACLs in advance

RECOMMEND: Rephrase

DrusTheAxe · 2026-07-06T17:12:37Z


+## 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) on the staged files for you. If you stage packages *manually* — for example, to an external volume, a network share, or a staging directory that remote or virtual desktops mount — you must set these ACLs yourself. Without them, registration can fail, or registration succeeds but the app fails to launch because the packaged process can't read its own files.


SUGGESTION (ACLs)

DrusTheAxe · 2026-07-06T17:13:45Z

+| Principal | SID | Access |
+|-----------|-----|--------|
+| `SYSTEM` | `S-1-5-18` | Full control |
+| `Administrators` | `S-1-5-32-544` | Full control |


We grant administrators Full control? That includes Write access. I'm surprised.

SUGGEST: Verify this table against latest version of the tool/code and update table to match, if necessary

DrusTheAxe · 2026-07-06T17:18:27Z

+| `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 required because a packaged app runs inside an app container with a reduced token. If these identities can't read the staged files, the app fails to launch even when registration reports success.


CAN run in an AppContainer. Not all do.

Also, 'process' is better than 'app'. Not all processes in a package are apps eg WinRT servers or processes for windows.appServices.

"can't read the staged files" - the permissions needed (and declared) are more than just read access, e.g. eXecute too.

SUGGESTION: 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) ensure such process can access the staged files. If these processes lack this access, they will fail to launch at runtime.

DrusTheAxe · 2026-07-06T17:19:50Z

+
+### 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 & execute** to each session host computer object, or, for easier management, to an Active Directory security group that contains those computer accounts, on **both**:


NIT: Read and eXecute

Alternatively, you could say 'Grant read and execute...' but the proper nouns reads more clearly here

Changed, but I'm not sure I understand why the "X" in "eXecute" needs to be capitalized.

DrusTheAxe · 2026-07-06T17:22:00Z

+
+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 & 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 **NTFS** permissions of the staged files and folders, and


NTFS isn't the only file system with Access Control Lists

SUGGESTION:

the staged files and folders

the file share

DrusTheAxe · 2026-07-06T17:22:15Z

-4. Users will only need to read access to the build folder.
+4. Users will only need read access to the build folder.
+
+5. For the registered package to launch, the build folder must also grant **Read & execute** to the app-container identities `ALL APPLICATION PACKAGES` (`S-1-15-2-1`) and `ALL RESTRICTED APPLICATION PACKAGES` (`S-1-15-2-2`). Without these, registration can succeed but the app fails to start because the packaged process can't read its files from the share. For the full set of staging permissions and `icacls` examples, see [Staging permissions (ACLs)](deploy-preinstalled-apps.md#staging-permissions-acls).


NIT: eXecute

Not sure I understand this comment...?

Fixed, but don't understand the capitalization of "X"

DrusTheAxe · 2026-07-06T17:22:50Z

-4. Users will only need to read access to the build folder.
+4. Users will only need read access to the build folder.
+
+5. For the registered package to launch, the build folder must also grant **Read & execute** to the app-container identities `ALL APPLICATION PACKAGES` (`S-1-15-2-1`) and `ALL RESTRICTED APPLICATION PACKAGES` (`S-1-15-2-2`). Without these, registration can succeed but the app fails to start because the packaged process can't read its files from the share. For the full set of staging permissions and `icacls` examples, see [Staging permissions (ACLs)](deploy-preinstalled-apps.md#staging-permissions-acls).


Similar phrasing as the AppContainer ACEs so see similar comment above re changes

Applies DrusTheAxe review threads 1-3,5-9: rephrase ACL intro (deployment sets ACLs when it can; read-only mounts require manual setup; pre-set to avoid one-time perf cost), link ACLs/ACEs to Learn security pages, rewrite app-container paragraph to reference packaged processes, use 'Read and eXecute' casing, drop NTFS/SMB-only framing, and reflow new prose to <=100 chars. Thread 4 (Administrators=Full control) left unchanged pending App Deployment team confirmation; not pushed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3d27fb29-0162-474f-8e83-e7cc06dfe11c

learn-build-service-prod · 2026-07-18T16:04:17Z

Learn Build status updates of commit 45a6b4a:

✅ Validation status: passed

File	Status	Preview URL	Details
msix-src/desktop/deploy-preinstalled-apps.md	✅Succeeded
msix-src/desktop/register-from-network.md	✅Succeeded
msix-src/msix-troubleshooting-guide.md	✅Succeeded

For more details, please refer to the build report.

RDMacLachlan requested review from DrusTheAxe and GrantMeStrength July 2, 2026 16:35

DrusTheAxe reviewed Jul 6, 2026

View reviewed changes

GrantMeStrength approved these changes Jul 8, 2026

View reviewed changes


		## 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) on the staged files for you. If you stage packages manually — for example, to an external volume, a network share, or a staging directory that remote or virtual desktops mount — you must set these ACLs yourself. Without them, registration can fail, or registration succeeds but the app fails to launch because the packaged process can't read its own files.


		### 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 & execute to each session host computer object, or, for easier management, to an Active Directory security group that contains those computer accounts, on both:


		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 & 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 NTFS permissions of the staged files and folders, and

Uh oh!

Conversation

RDMacLachlan commented Jul 2, 2026

Summary

Changes

Notes for reviewers

Uh oh!

learn-build-service-prod Bot commented Jul 2, 2026

✅ Validation status: passed

Uh oh!

RDMacLachlan commented Jul 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

learn-build-service-prod Bot commented Jul 18, 2026

✅ Validation status: passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants