Configure keychain

When the Microsoft Authentication Library (MSAL) for iOS and macOS signs in a user, or refreshes a token, it tries to cache tokens in the keychain. Caching tokens in the keychain allows MSAL to provide silent single sign-on (SSO) between multiple apps that are distributed by the same Apple developer. SSO is achieved via the keychain access groups functionality. For more information, see Apple's Keychain Items documentation.

This article covers how to configure app entitlements so that MSAL can write cached tokens to iOS and macOS keychain.

MSAL on iOS uses the com.microsoft.adalcache access group by default. This ensures the best SSO experience between multiple apps from the same publisher.

On iOS, add the com.microsoft.adalcache keychain group to your app's entitlement in XCode under Project settings > Capabilities > Keychain sharing.

MSAL on macOS uses com.microsoft.identity.universalstorage access group by default.

On MacOS, add the com.microsoft.identity.universalstorage keychain group to your app's entitlement in XCode under Project settings > Capabilities > Keychain sharing, similarly to iOS.

If you'd like to use a different keychain access group, you can pass your custom group when creating MSALPublicClientApplicationConfig before creating MSALPublicClientApplication, like this:

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"your-client-id"
                                                                                            redirectUri:@"your-redirect-uri"
                                                                                              authority:nil];
    
config.cacheConfig.keychainSharingGroup = @"custom-group";
    
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:nil];
    
// Now call `acquiretoken`. 
// Tokens will be saved into the "custom-group" access group
// and only shared with other applications declaring the same access group

let config = MSALPublicClientApplicationConfig(clientId: "your-client-id",
                                            redirectUri: "your-redirect-uri",
                                              authority: nil)
config.cacheConfig.keychainSharingGroup = "custom-group"
        
do {
  let application = try MSALPublicClientApplication(configuration: config)
  // continue on with application          
} catch let error as NSError {
  // handle error here
}       

If you don't want to share SSO state between multiple apps, or use any keychain access group, disable keychain sharing by passing the application bundle ID as your keychainGroup:

config.cacheConfig.keychainSharingGroup = [[NSBundle mainBundle] bundleIdentifier];

if let bundleIdentifier = Bundle.main.bundleIdentifier {
    config.cacheConfig.keychainSharingGroup = bundleIdentifier
}

Error -34018 normally means that the keychain hasn't been configured correctly. Ensure the keychain access group that has been configured in MSAL matches the one configured in entitlements.

On macOS, applications can execute without being signed by the developer. While most of MSAL's functionality will continue to work, SSO through keychain access requires application to be signed. If you're experiencing multiple keychain prompts, make sure your application's signature is valid.

Learn more about keychain access groups in Apple's Sharing Access to Keychain Items Among a Collection of Apps article.