[docs] Mandatory com.apple.security.network.client Entitlement for macOS Sandboxed Apps

[kanghohyeong]

When sandboxing and bundling a macOS app, it is necessary to include the following entitlement:

<key>com.apple.security.network.client</key>
<true/>

Without this, the app fails to function correctly.(white screen) While I am not entirely sure whether this requirement is due to Tauri’s backend-frontend communication architecture or the use of a WebView, I would greatly appreciate any insights on this.

Debugging and resolving this issue was extremely time-consuming and frustrating. I believe it would be beneficial to document this properly to help others facing the same problem.

Thank you!

[FabianLars]

Can you double check that with a fresh create-tauri-app project? Pretty sure I've seen a few sandboxed apps without that entitlement.

[kanghohyeong]

@FabianLars Hello! To debug this issue, I created a new project using the command npm create tauri-app@latest for testing. Without writing any code, I only added the entitlement and performed code signing. The application behaved exactly the same as the issue I encountered—showing only a white screen and not running properly.

After adding network.client, it worked properly.

[kanghohyeong]

Here is my build command npm run tauri build -- --no-bundle npm run tauri bundle -- --bundles app

[kanghohyeong]

I think this thread is probably relevant. I have also found a few suspicious logs.

결함	00:39:54.542584+0900	com.apple.WebKit.WebContent	Application does not have permission to communicate with network resources. rc=1 : errno=22
오류	00:39:54.556529+0900	entitlement-test	0x12001cc40 - [PID=0] WebProcessProxy::didFinishLaunching: Invalid connection identifier (web process failed to launch)
오류	00:39:54.556684+0900	entitlement-test	0x12001cc40 - [PID=0] WebProcessProxy::processDidTerminateOrFailedToLaunch: reason=Crash

[FabianLars]

I've found the source code of the app that worked without it but I can't retest it anymore due to missing access.

Anyway, doesn't matter, it was probably some weird fluke.

I appreciate the research you have done here :)

[tjramage]

@FabianLars @kanghohyeong – can confirm I have hit the exact same issue. I am assuming this is to do with Tauri's IPC architecture in order to enable communication between front and backend? See Apple's Entitlements reference for this: https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW9

Excerpt from above reference:

To enable your app to connect to a server process running on another machine (or on the same machine), enable outgoing network connections.

I am unsure if com.apple.security.network.server should also be included, but the Electron docs cover this.

For now, I have added both the client and server entitlements and finally everything loads up. Before this change, I was just getting a blank white screen, with the following relevant lines in system console:

com.apple.WebKit.Networking	[0x138609bc0] activating connection: mach=false listener=true peer=false name=com.apple.WebKit.Networking
com.apple.WebKit.WebContent	Application does not have permission to communicate with network resources. rc=1 : errno=1

My feeling is that this should be recommended (or at least mentioned) in the docs as a minimal Tauri setup when preparing your app for the App Store. Took me a while to stumble across this after searching with the above console error logs.

[FabianLars]

I am assuming this is to do with Tauri's IPC architecture in order to enable communication between front and backend?

Yeah i assume so but this would mean that the webview's inner implementation is a bit stupid cause it's not actually hitting the network (there's no actual localhost server or something involved)

I am unsure if com.apple.security.network.server should also be included, but the Electron docs cover this.

the ipc shouldn't need this so it depends on your app. if you spawn a localhost server on the rust side then i assume this is needed. unsure about something like SSE or websockets etc

My feeling is that this should be recommended (or at least mentioned) in the docs as a minimal Tauri setup when preparing your app for the App Store.

yep, agreed. that's why this issue here is still open :)

[Areopagitics]

This was a big time waster here as well ... committed something here 289a343facede42fbafbf95f419050f447984c63.

Hopefully this will close many issues.

@FabianLars @kanghohyeong – can confirm I have hit the exact same issue. I am assuming this is to do with Tauri's IPC architecture in order to enable communication between front and backend? See Apple's Entitlements reference for this: https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW9

Excerpt from above reference:

To enable your app to connect to a server process running on another machine (or on the same machine), enable outgoing network connections.

I am unsure if com.apple.security.network.server should also be included, but the Electron docs cover this.

For now, I have added both the client and server entitlements and finally everything loads up. Before this change, I was just getting a blank white screen, with the following relevant lines in system console:

com.apple.WebKit.Networking	[0x138609bc0] activating connection: mach=false listener=true peer=false name=com.apple.WebKit.Networking
com.apple.WebKit.WebContent	Application does not have permission to communicate with network resources. rc=1 : errno=1

My feeling is that this should be recommended (or at least mentioned) in the docs as a minimal Tauri setup when preparing your app for the App Store. Took me a while to stumble across this after searching with the above console error logs.