配置密钥链Configure keychain

如果适用于 iOS 和 macOS 的 Microsoft 身份验证库 (MSAL) 要将用户登录或刷新令牌,它会尝试在密钥链中缓存令牌。When the Microsoft Authentication Library for iOS and macOS (MSAL) signs in a user, or refreshes a token, it tries to cache tokens in the keychain. 通过在密钥链中缓存令牌,MSAL 可以在同一家 Apple 开发商分发的多个应用之间提供静默单一登录 (SSO)。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 是通过密钥链访问组功能实现的。SSO is achieved via the keychain access groups functionality. 有关详细信息,请参阅 Apple 的密钥链项文档For more information, see Apple's Keychain Items documentation.

本文介绍如何配置应用权利,使 MSAL 能够将缓存的令牌写入 iOS 和 macOS 密钥链。This article covers how to configure app entitlements so that MSAL can write cached tokens to iOS and macOS keychain.

默认的密钥链访问组Default keychain access group

iOSiOS

iOS 上的 MSAL 默认使用 com.microsoft.adalcache 访问组。MSAL on iOS uses the com.microsoft.adalcache access group by default. 它是 MSAL 和 Azure AD 身份验证库 (ADAL) SDK 使用的共享访问组,可确保在同一家发行商的多个应用之间提供最佳单一登录 (SSO) 体验。This is the shared access group used by both MSAL and Azure AD Authentication Library (ADAL) SDKs and ensures the best single sign-on (SSO) experience between multiple apps from the same publisher.

在 iOS 上,请在 XCode 中的“Project settings”(项目设置) > “Capabilities”(功能) > “Keychain sharing”(密钥链共享)下,将 com.microsoft.adalcache 密钥链组添加到应用的权利中 On iOS, add the com.microsoft.adalcache keychain group to your app's entitlement in XCode under Project settings > Capabilities > Keychain sharing

macOSmacOS

macOS 上的 MSAL 默认使用 com.microsoft.identity.universalstorage 访问组。MSAL on macOS uses com.microsoft.identity.universalstorage access group by default.

由于 macOS 密钥链的限制,在 macOS 10.14 和更低版本上,MSAL 的 access group 不会直接转换为密钥链访问组属性(请参阅 kSecAttrAccessGroup)。Due to macOS keychain limitations, MSAL's access group doesn't directly translate to the keychain access group attribute (see kSecAttrAccessGroup) on macOS 10.14 and earlier. 但是,从 SSO 的角度讲,MSAL 的行为类似,可确保同一家 Apple 开发商分发的多个应用程序提供静默 SSO。However, it behaves similarly from a SSO perspective by ensuring that multiple applications distributed by the same Apple developer can have silent SSO.

在 macOS 10.15 和更高版本 (macOS Catalina) 中,与 iOS 类似,MSAL 使用密钥链访问组属性来实现静默 SSO。On macOS 10.15 onwards (macOS Catalina), MSAL uses keychain access group attribute to achieve silent SSO, similarly to iOS.

自定义的密钥链访问组Custom keychain access group

若要使用不同的密钥链访问组,可以在创建 MSALPublicClientApplicationConfig 时传递自定义组,然后再创建 MSALPublicClientApplication,如下所示: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

禁用密钥链共享Disable keychain sharing

如果你不想要在多个应用之间共享 SSO 状态,或不想使用任何密钥链访问组,请通过传递应用程序捆绑 ID 作为 keychainGroup,来禁用密钥链共享: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];

处理 -34018 错误(无法将项设置为密钥链)Handle -34018 error (failed to set item into keychain)

错误 -34018 通常意味着未正确配置密钥链。Error -34018 normally means that the keychain hasn't been configured correctly. 确保 MSAL 中配置的密钥链访问组与权利中配置的访问组匹配。Ensure the keychain access group that has been configured in MSAL matches the one configured in entitlements.

确保应用程序已正确签名Ensure your application is properly signed

在 macOS 上,应用程序无需开发人员签名即可执行。On macOS, applications can execute without being signed by developer. 尽管 MSAL 的大部分功能可以继续工作,但通过密钥链访问实现的 SSO 要求为应用程序签名。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.

后续步骤Next steps

在 Apple 的 Sharing Access to Keychain Items Among a Collection of Apps(在一系列应用之间共享对密钥链项的访问权限)一文中详细了解密钥链访问组。Learn more about keychain access groups in Apple's Sharing Access to Keychain Items Among a Collection of Apps article.