将 Xamarin iOS 与 MSAL.NET 配合使用时的注意事项Considerations for using Xamarin iOS with MSAL.NET

在 Xamarin iOS 上使用适用于 .NET 的 Microsoft 身份验证库 (MSAL.NET) 时,应该:When you use Microsoft Authentication Library for .NET (MSAL.NET) on Xamarin iOS, you should:

  • 重写并实现 AppDelegate 中的 OpenUrl 函数。Override and implement the OpenUrl function in AppDelegate.
  • 启用密钥链组。Enable keychain groups.
  • 启用令牌缓存共享。Enable token cache sharing.
  • 启用密钥链访问。Enable keychain access.
  • 了解有关 iOS 12 和 iOS 13 以及身份验证的已知问题。Understand known issues with iOS 12 and iOS 13 and authentication.

实现 OpenUrlImplement OpenUrl

重写 FormsApplicationDelegate 派生类的 OpenUrl 方法,并调用 AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgsOverride the OpenUrl method of the FormsApplicationDelegate derived class and call AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs. 下面是一个示例:Here's an example:

public override bool OpenUrl(UIApplication app, NSUrl url, NSDictionary options)
{
    AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url);
    return true;
}

另外,请执行以下任务:Also, perform the following tasks:

  • 定义重定向 URI 方案。Define a redirect URI scheme.
  • 获取所需的权限,使应用能够调用另一个应用。Require permissions for your app to call another app.
  • 为重定向 URI 采用特定形式。Have a specific form for the redirect URI.
  • 在 Azure 门户中注册重定向 URIRegister a redirect URI in the Azure portal.

启用密钥链访问Enable keychain access

若要启用密钥链访问,请确保应用程序具有密钥链访问组。To enable keychain access, make sure that your application has a keychain access group. 创建应用程序时,可以使用 WithIosKeychainSecurityGroup() API 来设置密钥链访问组。You can set the keychain access group when you create your application by using the WithIosKeychainSecurityGroup() API.

若要从缓存和单一登录 (SSO) 中获益,请在所有应用程序中将密钥链访问组设置为相同的值。To benefit from the cache and single sign-on (SSO), set the keychain access group to the same value in all of your applications.

此设置示例使用 MSAL 4.x:This example of the setup uses MSAL 4.x:

var builder = PublicClientApplicationBuilder
     .Create(ClientId)
     .WithIosKeychainSecurityGroup("com.microsoft.adalcache")
     .Build();

此外,在 Entitlements.plist 文件中启用密钥链访问。Also enable keychain access in the Entitlements.plist file. 使用以下访问组或你自己的访问组。Use either the following access group or your own access group.

<dict>
  <key>keychain-access-groups</key>
  <array>
    <string>$(AppIdentifierPrefix)com.microsoft.adalcache</string>
  </array>
</dict>

使用 WithIosKeychainSecurityGroup() API 时,MSAL 会自动将安全组追加到应用程序团队 ID 的末尾 (AppIdentifierPrefix)。 When you use the WithIosKeychainSecurityGroup() API, MSAL automatically appends your security group to the end of the application's team ID (AppIdentifierPrefix). MSAL 之所以添加安全组,是因为当你在 Xcode 中生成应用程序时,它会执行相同的操作。MSAL adds your security group because when you build your application in Xcode, it will do the same. 正因如此,Entitlements.plist 文件中的权利需要在密钥链访问组的前面包含 $(AppIdentifierPrefix)That's why the entitlements in the Entitlements.plist file need to include $(AppIdentifierPrefix) before the keychain access group.

有关详细信息,请参阅 iOS 权利文档For more information, see the iOS entitlements documentation.

启用 iOS 应用程序之间的令牌缓存共享Enable token cache sharing across iOS applications

从 MSAL 2.x 开始,可以指定一个密钥链访问组,用于在多个应用程序之间保留令牌缓存。Starting in MSAL 2.x, you can specify a keychain access group to persist the token cache across multiple applications. 此设置可让你在使用相同密钥链访问组的多个应用程序之间共享令牌缓存。This setting enables you to share the token cache among several applications that have the same keychain access group. 可以在使用 ADAL.objcMSAL.objc 开发的 ADAL.NET 应用程序、MSAL.NET Xamarin.iOS 应用程序与本机 iOS 应用程序之间共享令牌缓存。You can share the token cache among ADAL.NET applications, MSAL.NET Xamarin.iOS applications, and native iOS applications that were developed in ADAL.objc or MSAL.objc.

通过共享令牌缓存,可以在使用相同密钥链访问组的所有应用程序之间实现单一登录 (SSO)。By sharing the token cache, you allow single sign-on (SSO) among all of the applications that use the same keychain access group.

若要启用此缓存共享,请在共享同一缓存的所有应用程序中,使用 WithIosKeychainSecurityGroup() 方法将密钥链访问组设置为相同的值。To enable this cache sharing, use the WithIosKeychainSecurityGroup() method to set the keychain access group to the same value in all applications that share the same cache. 本文中的第一个代码示例演示了如何使用该方法。The first code example in this article shows how to use the method.

本文前面已提到,每次使用 WithIosKeychainSecurityGroup() API 时,MSAL 都会添加 $(AppIdentifierPrefix)Earlier in this article, you learned that MSAL adds $(AppIdentifierPrefix) whenever you use the WithIosKeychainSecurityGroup() API. MSAL 之所以添加此元素,是因为团队 ID AppIdentifierPrefix 确保只有同一发布者构建的应用程序可以共享密钥链访问。MSAL adds this element because the team ID AppIdentifierPrefix ensures that only applications that are made by the same publisher can share keychain access.

备注

KeychainSecurityGroup 属性已弃用。The KeychainSecurityGroup property is deprecated. 改用 iOSKeychainSecurityGroup 属性。Use the iOSKeychainSecurityGroup property instead. 使用 iOSKeychainSecurityGroup 时,不要求有 TeamId 前缀。The TeamId prefix is not required when you use iOSKeychainSecurityGroup.

使用 Microsoft AuthenticatorUse Microsoft Authenticator

应用程序可以使用 Microsoft Authenticator(充当中介)来启用:Your application can use Microsoft Authenticator as a broker to enable:

  • SSO:启用 SSO 时,用户无需登录到每个应用程序。SSO: When you enable SSO, your users don't need to sign in to each application.
  • 设备标识:使用设备标识通过访问设备证书进行身份验证。Device identification: Use device identification to authenticate by accessing the device certificate. 当设备加入工作区时,将在设备上创建此证书。This certificate is created on the device when it's joined to the workplace. 如果租户管理员启用了与设备相关的条件访问,则应用程序将准备就绪。Your application will be ready if the tenant administrators enable conditional access related to the devices.
  • 应用程序标识验证:应用程序在调用中介时会传递其重定向 URL。Application identification verification: When an application calls the broker, it passes its redirect URL. 中介将验证重定向 URL。The broker verifies the redirect URL.

有关如何启用中介的详细信息,请参阅在 Xamarin iOS 和 Android 应用程序中使用 Microsoft Authenticator 或 Microsoft Intune 公司门户For details about how to enable a broker, see Use Microsoft Authenticator or Microsoft Intune Company Portal on Xamarin iOS and Android applications.

iOS 12 和身份验证的已知问题Known issues with iOS 12 and authentication

Microsoft 已发布安全公告,其中提供了有关 iOS 12 与某些身份验证类型之间的不兼容性的信息。Microsoft released a security advisory about an incompatibility between iOS 12 and some types of authentication. 这种不兼容性会中断社交、WSFed 和 OIDC 登录。该安全公告有助于了解如何删除应用程序中的 ASP.NET 安全限制,以使这些应用程序与 iOS 12 兼容。The incompatibility breaks social, WSFed, and OIDC sign-ins. The security advisory helps you understand how to remove ASP.NET security restrictions from your applications to make them compatible with iOS 12.

在 Xamarin iOS 上开发 MSAL.NET 应用程序的过程中,尝试从 iOS 12 登录到网站时,你可能会看到无限循环。When you develop MSAL.NET applications on Xamarin iOS, you might see an infinite loop when you try to sign in to websites from iOS 12. 此类行为类似于 GitHub 上的这一 ADAL 问题:尝试从 iOS 12 登录到网站时出现无限循环 #1329Such behavior is similar to this ADAL issue on GitHub: Infinite loop when trying to login to website from iOS 12 #1329.

此外,你还可能会看到 iOS 12 Safari 中发生 ASP.NET Core OIDC 身份验证中断。You might also see a break in ASP.NET Core OIDC authentication with iOS 12 Safari. 有关详细信息,请参阅此 WebKit 问题For more information, see this WebKit issue.

iOS 13 和身份验证方面的已知问题Known issues with iOS 13 and authentication

如果你的应用需要条件访问或证书身份验证支持,请让你的应用能够与 Microsoft Authenticator 代理应用通信。If your app requires conditional access or certificate authentication support, enable your app to communicate with the Microsoft Authenticator broker app. 然后,MSAL 会负责处理你的应用程序与 Microsoft Authenticator 之间的请求和响应。MSAL is then responsible for handling requests and responses between your application and Microsoft Authenticator.

在 iOS 13 上,Apple 删除了应用程序在通过自定义 URL 方案从外部应用程序接收响应时读取源应用程序的功能,进行了一项重大的 API 更改。On iOS 13, Apple made a breaking API change by removing the application's ability to read the source application when receiving a response from an external application through custom URL schemes.

Apple 关于 UIApplicationOpenURLOptionsSourceApplicationKey 的文档中有如下说明:Apple's documentation for UIApplicationOpenURLOptionsSourceApplicationKey states:

如果请求源自属于你的团队的另一个应用,UIKit 会将此键的值设置为该应用的 ID。如果源应用的团队标识符不同于当前应用的团队标识符,则该键的值为 nil。If the request originated from another app belonging to your team, UIKit sets the value of this key to the ID of that app. If the team identifier of the originating app is different than the team identifier of the current app, the value of the key is nil.

此更改对 MSAL 有重大影响,因为它依赖于 UIApplication.SharedApplication.OpenUrl 来验证 MSAL 和 Microsoft Authenticator 应用之间的通信。This change is breaking for MSAL because it relied on UIApplication.SharedApplication.OpenUrl to verify communication between MSAL and the Microsoft Authenticator app.

另外,在 iOS 13 上,开发人员在使用 ASWebAuthenticationSession 时需要提供呈现控制器。Additionally, on iOS 13, the developer is required to provide a presentation controller when using ASWebAuthenticationSession.

如果你使用 Xcode 11 进行生成,并且使用 iOS 代理或者 ASWebAuthenticationSession,你的应用就会受影响。Your app is impacted if you're building with Xcode 11 and you use either iOS broker or ASWebAuthenticationSession.

在这些情况下,请使用 MSAL.NET 4.4.0+,以便能够成功进行身份验证。In such cases, use MSAL.NET 4.4.0+ to enable successful authentication.

其他需求Additional requirements

  • 使用最新的 MSAL 库时,请确保设备上安装了 Microsoft Authenticator 6.3.19 或更高版本。When using the latest MSAL libraries, ensure that Microsoft Authenticator version 6.3.19+ is installed on the device.

  • 更新到 MSAL.NET 4.4.0 或更高版本时,请更新 info.plist 文件中的 LSApplicationQueriesSchemes 并添加 msauthv3When updating to MSAL.NET 4.4.0+, update the your LSApplicationQueriesSchemes in the Info.plist file and add msauthv3:

    <key>LSApplicationQueriesSchemes</key>
    <array>
         <string>msauthv2</string>
         <string>msauthv3</string>
    </array>
    

    对于在支持 iOS 13 的设备上检测是否存在最新 Microsoft Authenticator 应用程序而言,将 msauthv3 添加到 info.plist 是必要的。Adding msauthv3 to Info.plist is necessary to detect the presence of the latest Microsoft Authenticator app on the device that supports iOS 13.

报告问题Report an issue

如果你有问题,或者需要报告在 MSAL.NET 中发现的问题,请在 GitHub 上的 AzureAD/microsoft-authentication-library-for-dotnet 存储库中创建问题。If you have questions or would like to report an issue you've found in MSAL.NET, open an issue in the AzureAD/microsoft-authentication-library-for-dotnet repository on GitHub.

后续步骤Next steps

有关 Xamarin iOS 属性的信息,请参阅以下示例的 README.md 文件的特定于 iOS 的注意事项段落:For information about properties for Xamarin iOS, see the iOS-specific considerations paragraph of the following sample's README.md file:

示例Sample 平台Platform 说明Description
https://github.com/Azure-Samples/active-directory-xamarin-native-v2 Xamarin iOS、Android、通用 Windows 平台 (UWP)Xamarin iOS, Android, Universal Windows Platform (UWP) 一个简单的 Xamarin Forms 应用,演示如何通过 Azure AD 2.0 终结点使用 MSAL 进行 Azure AD 身份验证。A simple Xamarin Forms app that shows how to use MSAL to authenticate Azure AD via the Azure AD 2.0 endpoint. 该应用还演示如何使用生成的令牌来访问 Microsoft Graph。The app also shows how to use the resulting token to access Microsoft Graph.