将使用 Microsoft Authenticator 的 iOS 应用程序从 ADAL.NET 迁移到 MSAL.NETMigrate iOS applications that use Microsoft Authenticator from ADAL.NET to MSAL.NET

你使用适用于 .NET 的 Azure Active Directory 身份验证库 (ADAL.NET) 和 iOS 中介已有一段时间,You've been using the Azure Active Directory Authentication Library for .NET (ADAL.NET) and the iOS broker. 现在是时候迁移到适用于 .NET 的 Microsoft 身份验证库 (MSAL.NET) 了,从版本 4.3 开始,该库支持 iOS 上的中介。Now it's time to migrate to the Microsoft Authentication Library for .NET (MSAL.NET), which supports the broker on iOS from release 4.3 onward.

要从哪里入手?Where should you start? 本文会帮助你将 Xamarin iOS 应用从 ADAL 迁移到 MSAL。This article helps you migrate your Xamarin iOS app from ADAL to MSAL.

先决条件Prerequisites

本文假设你已有一个与 iOS 中介集成的 Xamarin iOS 应用。This article assumes that you already have a Xamarin iOS app that's integrated with the iOS broker. 如果没有,请直接迁移到 MSAL.NET,然后在其中开始实施中介。If you don't, move directly to MSAL.NET and begin the broker implementation there. 有关如何使用新应用程序调用 MSAL.NET 中的 iOS 中介的信息,请参阅此文档For information on how to invoke the iOS broker in MSAL.NET with a new application, see this documentation.

背景Background

什么是中介?What are brokers?

中介是 Microsoft 在 Android 和 iOS 上提供的应用程序。Brokers are applications provided by Microsoft on Android and iOS. (请参阅 iOS 和 Android 上的 Microsoft Authenticator 应用以及 Android 上的 Intune 公司门户应用。)(See the Microsoft Authenticator app on iOS and Android, and the Intune Company Portal app on Android.)

中介可以实现:They enable:

从 ADAL 迁移到 MSALMigrate from ADAL to MSAL

步骤 1:启用中介Step 1: Enable the broker

当前 ADAL 代码:Current ADAL code:对应的 MSAL 代码:MSAL counterpart:
在 ADAL.NET 中,中介支持将按身份验证上下文启用。In ADAL.NET, broker support was enabled on a per-authentication context basis. 此项默认禁用。It's disabled by default. 必须在You had to set a

PlatformParameters 构造函数中将 useBroker 标志设置为 true 才能调用中介:useBroker flag to true in the PlatformParameters constructor to call the broker:

public PlatformParameters(
        UIViewController callerViewController,
        bool useBroker)

此外,在特定于平台的代码中(对于本示例,是在 iOS 的页面呈现器中)将 useBrokerAlso, in the platform-specific code, in this example, in the page renderer for iOS, set the useBroker 标志设置为 true:flag to true:

page.BrokerParameters = new PlatformParameters(
          this,
          true,
          PromptBehavior.SelectAccount);

然后,在获取令牌调用中包含参数:Then, include the parameters in the acquire token call:

 AuthenticationResult result =
                    await
                        AuthContext.AcquireTokenAsync(
                              Resource,
                              ClientId,
                              new Uri(RedirectURI),
                              platformParameters)
                              .ConfigureAwait(false);
在 MSAL.NET 中,中介支持是按 PublicClientApplication 启用的。In MSAL.NET, broker support is enabled on a per-PublicClientApplication basis. 此项默认禁用。It's disabled by default. 若要启用它,请使用To enable it, use the

WithBroker() 参数(默认设置为 true)以调用中介:WithBroker() parameter (set to true by default) in order to call the broker:

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos)
                .Build();

在“获取令牌”调用中:In the acquire token call:

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow(App.RootViewController)
             .ExecuteAsync();

步骤 2:设置 UIViewController()Step 2: Set a UIViewController()

在 ADAL.NET 中,已传入 UIViewController 作为 PlatformParameters 的一部分。In ADAL.NET, you passed in a UIViewController as part of PlatformParameters. (请参阅“步骤 1”中的示例。)在 MSAL.NET 中,为了让开发人员获得更大的灵活性,将使用对象窗口,但在一般的 iOS 用途中不需要使用它。(See the example in Step 1.) In MSAL.NET, to give developers more flexibility, an object window is used, but it's not required in regular iOS usage. 若要使用中介,请设置对象窗口,以便与中介相互发送和接收响应。To use the broker, set the object window in order to send and receive responses from the broker.

当前 ADAL 代码:Current ADAL code:对应的 MSAL 代码:MSAL counterpart:
UIViewController 将传入A UIViewController is passed into

iOS 特定平台中的 PlatformParametersPlatformParameters in the iOS-specific platform.

page.BrokerParameters = new PlatformParameters(
          this,
          true,
          PromptBehavior.SelectAccount);
在 MSAL.NET 中,请执行以下两项操作来设置 iOS 的对象窗口:In MSAL.NET, you do two things to set the object window for iOS:
  1. AppDelegate.cs 中,将 App.RootViewController 设置为新的 UIViewController()In AppDelegate.cs, set App.RootViewController to a new UIViewController(). 这种分配可确保提供一个 UIViewController 来调用中介。This assignment ensures that there's a UIViewController with the call to the broker. 如果未正确设置此参数,可能会收到以下错误:"uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker"If it isn't set correctly, you might get this error: "uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker"
  2. 在 AcquireTokenInteractive 调用中,使用 .WithParentActivityOrWindow(App.RootViewController) 并传入对你要使用的对象窗口的引用。On the AcquireTokenInteractive call, use .WithParentActivityOrWindow(App.RootViewController), and pass in the reference to the object window you'll use.

例如:For example:

App.cs中:In App.cs:

   public static object RootViewController { get; set; }

AppDelegate.cs中:In AppDelegate.cs:

   LoadApplication(new App());
   App.RootViewController = new UIViewController();

在“获取令牌”调用中:In the acquire token call:

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow(App.RootViewController)
             .ExecuteAsync();

步骤 3:更新 AppDelegate 以处理回调Step 3: Update AppDelegate to handle the callback

ADAL 和 MSAL 都会调用中介,而中介通过 AppDelegate 类的 OpenUrl 方法回调应用程序。Both ADAL and MSAL call the broker, and the broker in turn calls back to your application through the OpenUrl method of the AppDelegate class. 有关详细信息,请参阅此文档For more information, see this documentation.

ADAL.NET 和 MSAL.NET 在此方面没有差别。There are no changes here between ADAL.NET and MSAL.NET.

步骤 4:注册 URL 方案Step 4: Register a URL scheme

ADAL.NET 和 MSAL.NET 使用 URL 调用中介,然后将中介响应返回到应用。ADAL.NET and MSAL.NET use URLs to invoke the broker and return the broker response back to the app. 按如下所示在应用的 Info.plist 文件中注册 URL 方案:Register the URL scheme in the Info.plist file for your app as follows:

当前 ADAL 代码:Current ADAL code:对应的 MSAL 代码:MSAL counterpart:
URL 方案对于应用是唯一的。The URL scheme is unique to your app. 必须向The

CFBundleURLSchemes 名称必须包含CFBundleURLSchemes name must include

msauth.

作为前缀,后接 CFBundleURLNameas a prefix, followed by your CFBundleURLName

例如:$"msauth.(BundleId")For example: $"msauth.(BundleId")

 <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.xforms</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>msauth.com.yourcompany.xforms</string>
        </array>
      </dict>
    </array>

备注

此 URL 方案会成为重定向 URI 的一部分,该 URI 用于在应用接收中介的响应时对应用进行唯一标识。This URL scheme becomes part of the redirect URI that's used to uniquely identify the app when it receives the response from the broker.

步骤 5:将中介标识符添加到 LSApplicationQueriesSchemes 节Step 5: Add the broker identifier to the LSApplicationQueriesSchemes section

ADAL.NET 和 MSAL.NET 都使用 -canOpenURL: 来检查是否在设备上安装了中介。ADAL.NET and MSAL.NET both use -canOpenURL: to check if the broker is installed on the device. 按如下所示,将 iOS 中介的正确标识符添加到 info.plist 文件的 LSApplicationQueriesSchemes 节:Add the correct identifier for the iOS broker to the LSApplicationQueriesSchemes section of the info.plist file as follows:

当前 ADAL 代码:Current ADAL code:对应的 MSAL 代码:MSAL counterpart:
使用Uses

msauth

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauth</string>
</array>
使用Uses

msauthv2

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

步骤 6:在 Azure 门户中注册重定向 URIStep 6: Register your redirect URI in the Azure portal

在以中介为目标时,ADAL.NET 和 MSAL.NET 都在重定向 URI 方面施加额外的要求。ADAL.NET and MSAL.NET both add an extra requirement on the redirect URI when it targets the broker. 在 Azure 门户中将重定向 URI 注册到应用程序。Register the redirect URI with your application in the Azure portal.

当前 ADAL 代码:Current ADAL code:对应的 MSAL 代码:MSAL counterpart:

"<app-scheme>://<your.bundle.id>"

示例:Example:

mytestiosapp://com.mycompany.myapp

$"msauth.{BundleId}://auth"

示例:Example:

public static string redirectUriOnIos = "msauth.com.yourcompany.XForms://auth";

若要详细了解如何在 Azure 门户中注册重定向 URI,请参阅步骤 7:向应用注册中添加重定向 URIFor more information about how to register the redirect URI in the Azure portal, see Step 7: Add a redirect URI to your app registration.

步骤 7:设置 Entitlements.plistStep 7: Set the Entitlements.plist

在 Entitlements.plist 文件中启用密钥链访问:Enable keychain access in the Entitlements.plist file:

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

若要详细了解如何启用密钥链访问,请参阅启用密钥链访问For more information about enabling keychain access, see Enable keychain access.

后续步骤Next steps

了解与 MSAL.NET 配合使用时特定于 Xamarin iOS 的注意事项Learn about Xamarin iOS-specific considerations with MSAL.NET.