Accessing app group containers in your existing macOS app

Ensure your app has app group container entitlements and macOS can authorize them.

Overview

In macOS 15 and later, app group containers offer System Integrity Protection for your app’s local files even if the app doesn’t have the App Sandbox capability. These app group containers limit access by apps that aren’t in the app group. Apps not in the app group that attempt to access locations within an app group or app data container, result in a user prompt that requests their authorization.

To ensure your apps that use app groups also include System Integrity Protection, you need to confirm they have the correct entitlements and macOS can authorize those entitlements. For more information on adding an app group to an app, see Configuring app groups.

Apps that can use app group containers include: main executables packaged in bundled structures, app extensions, App Clips, and XPC Services.

Add app group membership to your app

Ensure that your app target lists all the app groups to which it belongs in the App Groups Entitlement. You can use Xcode to entitle your app for app groups. For more details, see Configuring app groups.

An app can belong to more than one app group, with these guidelines:

Different developer teams can’t use the same app group.
The same developer team can share the same app group for multiple apps and supporting processes signed by that team.

Use provisioned app groups

If your app declares that it belongs to an app group that begins with group., you need to include the group in your app’s provisioning profile.

Include all the restricted entitlements, including the app group entitlement, in the provisioning profile of the process; the values of these entitlements must match and account for any wildcards in the provisioning profile entitlements.

Provisioning profiles for macOS apps that you previously created might not include authorization for the app group entitlement. You can check whether macOS set the entitlements validated flag on your process at runtime by running the command sudo launchctl procinfo <pid> in Terminal:

% sudo launchctl procinfo `pgrep <your app's executable file name>`
…
code signing info = valid
    …
    entitlements validated
…

Xcode automatically obtains new provisioning profiles if you check “Automatically manage signing” in the Signing & Capabilities editor for your app target, and set the REGISTER_APP_GROUPS build setting to Yes. To apply a provisioning profile to a daemon, or another executable file that you don’t distribute in a bundle, see Signing a daemon with a restricted entitlement.

If you encounter any issues provisioning the app group entitlement properly, see Diagnosing Issues with Entitlements for help diagnosing these issues.

Use app groups that you don’t provision

To use app groups that have the <Developer team identifier>.<group name> identifiers on macOS, you don’t need a provisioning profile. The system checks that the team identifier prefix matches the developer team identifier you use to sign the app. You also don’t need to register these app group identifiers on the Developer website. But, there are limitations to using these identifiers:

<Developer team identifier>.<group name> is not supported on iOS, iPadOS, tvOS, visionOS, or watchOS.
Keychain Access Groups doesn’t support the <Developer team identifier>.<group name> prefixed identifier. For more information, see Sharing access to keychain items among a collection of apps

Access an app group container

When your app becomes a member of an app group, use FileManager APIs to get the path to the shared container. For more details on accessing that data, see Access an app group’s shared container.