將使用 Microsoft Authenticator 的 iOS 應用程式從 ADAL.NET 移轉至 MSAL.NET

  • 發行項

您已使用適用於 .NET (ADAL.NET) 和 iOS 訊息代理程式的 Azure Active Directory Authentication Library。 現在可以開始移轉至適用於 .NET 的 Microsoft 驗證程式庫 (MSAL.NET)，此程式庫從 4.3 版開始支援 iOS 上的訊息代理程式。

您該從何處著手？ 本文可協助您將 Xamarin iOS 應用程式從 ADAL 移轉至 MSAL。

必要條件

本文假設您已經有整合了 iOS 訊息代理程式的 Xamarin iOS 應用程式。 如果您沒有這麼做，請直接移至 MSAL.NET，並在該處開始訊息代理程式實作。 如需如何使用新的應用程式在 MSAL.NET 中叫用 iOS 訊息代理程式的詳細資訊，請參閱此文件。

背景

什麼是訊息代理程式？

訊息代理程式是 Microsoft 在 Android 和 iOS 上提供的應用程式。 (參閱 iOS 和 Android 上的 Microsoft Authenticator 應用程式，以及 Android 上的 Intune 公司入口網站應用程式。 )

這些應用程式會啟用：

從 ADAL 移轉至 MSAL

步驟 1︰啟用訊息代理程式

目前的 ADAL 程式碼：MSAL 對應項目：
在 ADAL.NET 中，會根據驗證的內容基礎來啟用訊息代理程式支援。 此項目預設為停用。 您必須設定

useBroker 旗標為 True (在 PlatformParameters 建構函式中)，以呼叫訊息代理程式：

public PlatformParameters(
        UIViewController callerViewController,
        bool useBroker)

此外，在此範例中的平台特定程式碼中，於 iOS 的頁面轉譯器中，設定 useBroker 旗標為 True：

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

然後，將參數包含在取得權杖呼叫中：

 AuthenticationResult result =
                    await
                        AuthContext.AcquireTokenAsync(
                              Resource,
                              ClientId,
                              new Uri(RedirectURI),
                              platformParameters)
                              .ConfigureAwait(false);
在 MSAL.NET 中，會根據 PublicClientApplication 基礎啟用訊息代理程式支援。 此項目預設為停用。 若要啟用，請使用

WithBroker() 參數 (依預設設定為 True)，以便呼叫訊息代理程式：

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

在取得權杖呼叫中：

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

步驟 2：設定 UIViewController ()

在 ADAL.NET 中，您會在 UIViewController 中做為 PlatformParameters 的一部分傳遞。 (請參閱步驟 1 中的範例。)在 MSAL.NET 中，為了讓開發人員擁有更大的彈性，會使用物件視窗，但在一般的 iOS 使用方式中則不需要。 若要使用訊息代理程式，請設定物件視窗，以便從訊息代理程式傳送和接收回應。

目前的 ADAL 程式碼：MSAL 對應項目：
UIViewController 會傳入

PlatformParameters 在 iOS 特定平台中。

page.BrokerParameters = new PlatformParameters(
          this,
          true,
          PromptBehavior.SelectAccount);
在 MSAL.NET 中，您可以執行兩項作業來設定 iOS 的物件視窗：
  1. 在 AppDelegate.cs 中，將 App.RootViewController 設定為新的 UIViewController()。 此指派可確保有 UIViewController 與訊息代理程式的呼叫。 如果設定不正確，您可能會收到此錯誤："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) 並傳入您將使用的物件視窗參考。

例如：

在 App.cs 中：

   public static object RootViewController { get; set; }

在 AppDelegate.cs 中：

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

在取得權杖呼叫中：

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

步驟 3：更新 AppDelegate 以處理回呼

ADAL 和 MSAL 都會呼叫訊息代理程式，而訊息代理程式接著會透過 AppDelegate 類別的方法 OpenUrl，回呼至您的應用程式。 如需詳細資訊，請參閱這份文件。

ADAL.NET 與 MSAL.NET 之間沒有任何變更。

步驟 4︰註冊 URL 配置

ADAL.NET 和 MSAL.NET 會使用 URL 叫用訊息代理程式，並將訊息代理程式回應傳回給應用程式。 在應用程式的 Info.plist 檔案中註冊 URL 配置，如下所示：

目前的 ADAL 程式碼：MSAL 對應項目：
URL 配置對您的應用程式為唯一。

CFBundleURLSchemes 名稱必須包含

msauth.

作為前置詞，後面接著您的 CFBundleURLName

例如：$"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 的一部分，當應用程式收到來自訊息代理程式的回應時，會將其用來唯一識別該應用程式。

步驟 5：將訊息代理程式識別碼新增至 LSApplicationQueriesSchemes 區段

ADAL.NET 和 MSAL.NET 都是用 -canOpenURL: 來檢查訊息代理程式是否已安裝在裝置上。 將正確的 iOS 訊息代理程式識別碼新增至 info.plist 檔案的 LSApplicationQueriesSchemes 區段，如下所示：

目前的 ADAL 程式碼：MSAL 對應項目：
使用

msauth

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

msauthv2

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

步驟 6：在 Azure 入口網站中註冊您的重新導向 URI

ADAL.NET 和 MSAL.NET 會在以訊息代理程式為目標時，對重新導向 URI 新增額外的需求。 在 Azure 入口網站中向您的應用程式註冊重新導向 URI。

目前的 ADAL 程式碼：MSAL 對應項目：

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

範例：

mytestiosapp://com.mycompany.myapp

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

範例：

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

如需關於在 Azure 入口網站中註冊重新導向 URI 的詳細資訊，請參閱步驟 7：將重新導向 URI 新增至您的應用程式註冊。

步驟 7：設定 Entitlements.plist

在 Entitlements.plist 檔案中啟用金鑰鏈存取：

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

如需啟用金鑰鏈存取的詳細資訊，請參閱啟用金鑰鏈存取。

下一步

了解 MSAL.NET 的 Xamarin iOS 特定考量。