KeyChain Sharing with App Extensions

What platform are you on?

And what type of app extensions are you building?

This matters because:

• You tagged your thread with Network Extension, which suggests you’re building an NE provider.
• On macOS, the keychain is weird. See TN3137 On Mac keychain APIs and implementations.
• And NE providers can be packaged as either an appex or a sysex. See TN3134 Network Extension provider deployment.
• And that affects how you should interact with the keychain. See Network Extension Provider Packaging.

So, if you’re on iOS or one of its child platforms, we can focus on the appex side of this. OTOH, if you’re on macOS, things get more complex |-:

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Hi Apple team,

Thanks for the follow up. Here are the details you requested:

• Platform: iOS (running on iPhone hardware; built with Xcode 15, iOS 17 SDK).
• Extension type: Network Extension provider packaged as an app extension (appex) within the main app target.
• Keychain configuration:
  • The main app and the extension both have the Keychain Sharing capability enabled with the same access group (for example, ABCD1234.com.example.shared).
  • We also tried the common app group and specifying the access group via kSecAttrAccessGroup, including variations such as $AppIdentifier.KeyChainSharingGroup.
• Error observed: When the extension attempts to access the shared keychain, SecItemCopyMatching returns status 25291 (errSecNotAvailable), which Xcode reports as "No keychain is available." The same code and access group work from the containing app.

Could you advise whether additional entitlements are needed for Network Extension providers on iOS, or if there are specific packaging or provisioning steps we should double-check for appex-based NE providers? If there are recommended examples for keychain access from NE appexes, we would appreciate a pointer.

Thanks for your help!

Hi,

Thanks for following up.

Platform: iOS (tested on iOS 17.x and iOS 18 betas).

Extension type: Apple MatterSupport “Matter Add Device Extension” (Accessory Setup extension). We’re not building a Network Extension provider—our earlier “Network Extension” tag was a mistake.

Our setup is a standard iOS app (com.infibrite…) plus the Matter setup extension (com.infibrite…MatterSetupExtension). Both targets need to share Matter fabric credentials via a single keychain access group (com.infibrite.matter.shared) so the extension can commission devices while the main app reuses the stored fabric.

App Groups and other capabilities enable correctly, but the “Keychain Sharing” toggle never appears for either App ID in the portal. Because the provisioning profiles can’t include that entitlement, the OS returns errSecMissingEntitlement whenever we reference kSecAttrAccessGroup, so the extension can’t read the credentials.

Could you enable Keychain Sharing for these iOS App IDs (main app + Matter setup extension) or let us know how to make the capability visible? Happy to provide the exact bundle identifiers if needed.

Thanks again for the assistance! Best regards,

our earlier “Network Extension” tag was a mistake.

And presumably so was the reply you posted about 10 hours before this one |-:

Anyway, the behaviour you’ve described doesn’t gel with Network Extension at all, so I’ve re-tagged your thread accordingly.

When dealing with keychain sharing, there are two factors in play:

• Build time
• Run time

I’m gonna focus on the build-time stuff, because a) that’s where you seem to be stuck, and b) I’m not familiar with Matter extensions and there could be run-time restrictions I’m not familiar with.

So, regarding your build, you wrote:

Could you enable Keychain Sharing for these iOS App IDs … ?

There’s nothing for us to enable here. Every App ID supports keychain sharing [1].

To illustrate this:

1. I using Xcode 26.1 to create a new test project from the iOS > App template.
2. Within that, I created a new iOS > Matter Extension target.
3. In Signing & Capabilities, I add the Keychain Sharing capability to both.
4. And entered Test809012.shared into the list of keychain access groups.
5. I built the app (for the device, not for the simulator).

I then started digging into the built product. First, here are the entitlements claimed:

% codesign -d --entitlements - Test809012.app                        
…
[Dict]
	[Key] application-identifier
	[Value]
		[String] SKMME9E2Y8.com.example.apple-samplecode.Test809012
    …
	[Value]
		[Array]
			[String] SKMME9E2Y8.Test809012.shared
% codesign -d --entitlements - Test809012.app/PlugIns/NotEnergy.appex
…
[Dict]
	[Key] application-identifier
	[Value]
		[String] SKMME9E2Y8.com.example.apple-samplecode.Test809012.NotEnergy
    …
	[Key] keychain-access-groups
	[Value]
		[Array]
			[String] SKMME9E2Y8.Test809012.shared

That is, both the app and the appex claim access to the SKMME9E2Y8.Test809012.shared.

And here are the entitlements authorised by the profile:

% security cms -D -i Test809012.app/embedded.mobileprovision | plutil -p -
{
  …
  "Entitlements" => {
    "application-identifier" => "SKMME9E2Y8.com.example.apple-samplecode.*"
    …
    "keychain-access-groups" => [
      0 => "SKMME9E2Y8.*"
      1 => "com.apple.token"
    ]
  }
  …
}
% security cms -D -i Test809012.app/PlugIns/NotEnergy.appex/embedded.mobileprovision | plutil -p -
{
  …
  "Entitlements" => {
    "application-identifier" => "SKMME9E2Y8.com.example.apple-samplecode.*"
    …
    "keychain-access-groups" => [
      0 => "SKMME9E2Y8.*"
      1 => "com.apple.token"
    ]
  }
  …
}

In both cases the profiles authorise SKMME9E2Y8.*. This wildcard syntax allows the app to claim access to any keychain access group starting with SKMME9E2Y8., and that includes the SKMME9E2Y8.Test809012.shared group that the programs claim.

Note The com.apple.token value is always present; it’s needed for iOS apps to access token-based credentials. Also, the above shows that Xcode chose to use my wildcard App ID, SKMME9E2Y8.com.example.apple-samplecode.*, rather than an explicit App ID. That’s because neither the app nor the appex claim any entitlements that require an explicit App ID.

AFAICT your team has two App IDs registered:

• S________S.c__.M_____.I________ for the app
• S________S.c__.M_____.I________.____________________ for the appex

Both of these support keychain sharing straight out of the box.

the “Keychain Sharing” toggle never appears for either App ID in the portal.

Right. That’s normal. The Developer website shows no UI for this capability because it’s always enabled for all App IDs [1]. The only reason Xcode shows it in Signing & Capabilities is so that you can configure the list of keychain access groups that you claim.

I recommend that you re-test this based on the explanation above. First try this in your app, making sure that you’re able to read and write the keychain access group that you claim. Then repeat the process for your Matter extension, to see if you run into any issues on that side of the fence.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] Well, almost. This does include both explicit and wildcard App IDs, but it doesn’t include App IDs with a unique App ID prefix. Those are effectively deprecated and I’ve confirmed that they’re not involved here.