DTS regularly receives questions about how to preserve keychain items across an App ID change, and so I thought I’d post a comprehensive answer here for the benefit of all.
If you have any questions or comments, please start a new thread here on the forums. Put it in the Privacy & Security > General subtopic and tag it with Security.
Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"
App ID Prefix Change and Keychain Access
The list of keychain access groups your app can access is determined by three entitlements. For the details, see Sharing Access to Keychain Items Among a Collection of Apps. If your app changes its App ID prefix, this list changes and you’re likely to lose access to existing keychain items.
This situation crops up under two circumstances:
When you migrate your app from using a unique App ID prefix to using your Team ID as its App ID prefix.
When you transfer your app to another team.
In both cases you have to plan carefully for this change. If you only learn about the problem after you’ve made the change, consider undoing the change to give you time to come up with a plan before continuing.
Note On macOS, the information in this post only applies to the data protection keychain. For more information about the subtleties of the keychain on macOS, see On Mac Keychains.
For more about App ID prefix changes, see Technote 2311 Managing Multiple App ID Prefixes and QA1726 Resolving the Potential Loss of Keychain Access warning.
Migrate From a Unique App ID Prefix to Your Team ID
Historically each app was assigned its own App ID prefix. This is no longer the case. Best practice is for apps to use their Team ID as their App ID prefix. This enables multiple neat features, including keychain item sharing and pasteboard sharing.
If you have an app that uses a unique App ID prefix, consider migrating it to use your Team ID. This is a good thing in general, as long as you manage the migration process carefully.
Your app’s keychain access group list is built from three entitlements:
keychain-access-groups — For more on this, see Keychain Access Groups Entitlement.
application-identifier (com.apple.application-identifier on macOS)
com.apple.security.application-groups — For more on this, see App Groups Entitlement.
Keycahin access groups from the third bullet are call app group identified keychain access groups, or AGI keychain access groups for short.
IMPORTANT A macOS app can only use an AGI keychain access group if all of its entitlement claims are validated by a provisioning profile. See App Groups: macOS vs iOS: Working Towards Harmony for more about this concept.
Keychain access groups from the first two bullets depend on the App ID prefix. If that changes, you lose access to any keychain items in those groups.
WARNING Think carefully before using the keychain to store secrets that are the only way to access irreplaceable user data. While the keychain is very reliable, there are situations where a keychain item can be lost and it’s bad if it takes the user’s data with it.
In some cases losing access to keychain items is not a big deal. For example, if your app uses the keychain to manage a single login credential, losing that is likely to be acceptable. The user can recover by logging in again.
In other cases losing access to keychain items is unacceptable. For example, your app might manage access to dozens of different servers, each with unique login credentials. Your users will be grumpy if you require them to log in to all those servers again.
In such situations you must carefully plan your migration. The key thing to understand is that an app group is tied to your team, not your App ID prefix, and thus your app retains access to AGI keychain access groups across an App ID prefix change. This suggests the following approach:
Release a version of your app that moves keychain items from other keychain access groups to an AGI keychain access group.
Give your users time to update to this new version, run it, and so move their keychain items.
When you’re confident that the bulk of your users have done this, change your App ID prefix.
The approach has one obvious caveat: It’s hard to judge how long to wait at step 2.
Transfer Your App to Another Team
Historically there was no supported way to maintain access to keychain items across an app transfer. That’s no longer the case, but you must still plan the transfer carefully.
The overall approach is:
Identify an app group ID to transfer. This could be an existing app group ID, but in many cases you’ll want to register a new app group ID solely for this purpose.
Use the old team (the transferor) to release a version of your app that moves keychain items from other keychain access groups to the AGI keychain access group for this app group ID.
Give your users time to update to this new version, run it, and so move their keychain items.
When you’re confident that the bulk of your users have done this, initiate the app transfer.
Once that’s complete, transfer the app group ID you selected in step 1. See App Store Connect Help > Transfer an app > Overview of app transfer > Apps using App Groups.
Publish an update to your app from the new team (the transferee).
When a user installs this version, it will have access to your app group, and hence your keychain items.
WARNING Once you transfer the app group, the old team won’t be able to publish a new version of any app that uses this app group. That makes step 1 in the process critical. If you have an existing app group that’s used solely by the app being transferred — for example, an app group that you use to share state between the app and its app extensions — then choosing that app group ID makes sense. On the other hand, choosing the ID of an app group that’s share between this app and some unrelated app, one that’s not being transferred, would be bad, because any updates to that other app will lose access to the app group.
There are some other significant caveats:
The process doesn’t work for Mac apps because Mac apps that have ever used an app group can’t be transferred. See App Store Connect Help > Transfer an app > App transfer criteria.
If and when that changes, you’ll need to choose an iOS-style app group ID for your AGI keychain access group. For more about the difference between iOS- and macOS-style app group IDs, see App Groups: macOS vs iOS: Working Towards Harmony.
The current transfer process of app groups exposes a small window where some other team can ‘steal’ your app group ID. We have a bug on file to improve that process (r. 171616887).
The process works best when transferring between two teams that are both under the control of the same entity. If that’s not the case, take steps to ensure that the old team transfers the app group in step 5.
When you submit the app from the new team (step 6), App Store Connect will warn you about a potential loss of keychain access. That warning is talking about keychain items in normal keychain access groups. Items in an AGI keychain access group will still be accessible as long as you transfer the app group.
Alternative Approaches for App Transfer
In addition to the technique described in the previous section, there are a some alternative approaches you should at consider:
Do nothing
Do not transfer your app
Get creative
Do Nothing
In this case the user loses all the secrets that your app stored in the keychain. This may be acceptable for certain apps. For example, if your app uses the keychain to manage a single login credential, losing that is likely to be acceptable. The user can recover by logging in again.
Do Not Transfer
Another option is to not transfer your app. Instead, ship a new version of the app from the new team and have the old app recommend that the user upgrade.
There are a number of advantages to this approach. The first is that there’s absolutely no risk of losing any user data. The two apps are completely independent.
The second advantage is that the user can install both apps on their device at the same time. This opens up a variety of potential migration paths. For example, you might ship an update to the old app with an export feature that saves the user’s state, including their secrets, to a suitably encrypted file, and then match that with an import facility on the new app.
Finally, this approach offers flexible timing. The user can complete their migration at their leisure.
However, there are a bunch of clouds to go with these silver linings:
Your users might never migrate to the new app.
If this is a paid app, or an app with in-app purchase, the user will have to buy things again.
You lose the original app’s history, ratings, reviews, and so on.
Get Creative
Finally, you could attempt something creative. For example, you might:
Publish a new version of the app that supports exporting the user’s state, including the secrets.
Tell your users to do this, with a deadline.
Transfer the app and then, when the deadline expires, publish the new version with an import feature.
Frankly, this isn’t very practical. The problem is with step 2: There’s no good way to get all your users to do the export, and if they don’t do it before the deadline there’s no way to do it after.
Revision History
2026-03-31 Rewrote the Transfer Your App to Another Team section to describe a new approach for preserving access to keychain items across app transfers. Moved the previous discussion into a new Alternative Approaches for App Transfer section. Clarified that a macOS program can now use an app group as a keychain access group as long as its entitlements are validated. Made numerous editorial changes.
2022-05-17 First posted.
0
0
8.5k