設定可呼叫 Web API 的行動應用程式

發行項
07/03/2024

建立應用程式之後，您將瞭解如何使用應用程式註冊參數來設定程式碼。行動應用程式會帶來一些與建立架構相關的複雜性。

支援行動應用程式的 Microsoft 程式庫

下列 Microsoft 程式庫支援行動應用程式：

平台	專案平台 GitHub	套件	開始啟動	正式發行 (GA) 或公開預覽¹
Android (Java)	MSAL Android	MSAL (部分機器翻譯)	快速入門	GA
Android (Kotlin)	MSAL Android	MSAL (部分機器翻譯)	—	GA
iOS (Swift/Obj-C)	適用於 iOS 和 macOS 的 MSAL	MSAL (部分機器翻譯)	教學課程	GA
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	GA

¹ 在線服務的通用授權條款適用於公開預覽中的連結庫。

具現化應用程式

Android

行動應用程式會使用 PublicClientApplication 類別。以下是如何將其具現化：

PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

iOS

iOS 上的行動應用程式需要具現化 MSALPublicClientApplication 類別。若要具現化類別，請使用下列程式碼。

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

其他 MSALPublicClientApplicationConfig 屬性可以覆寫預設授權單位、指定重新導向 URI，或變更 MSAL 權杖快取的行為。

Xamarin 或 UWP

本節說明如何將適用於 Xamarin.iOS、Xamarin.Android 和 UWP 應用程式的應用程式具現化。

注意

MSAL.NET 版本 4.61.0 和更新版本不支援通用 Windows 平台 (UWP)、Xamarin Android 和 Xamarin iOS。建議您將 Xamarin 應用程式移轉至 MAUI 等新式架構。在宣佈即將淘汰適用於 Xamarin 和 UWP 的 MSAL.NET 中深入了解此淘汰。

具現化應用程式

在 Xamarin 或 UWP 中，具現化應用程式的最簡單方式是使用下列程式碼。在此程式碼中，ClientId 是已註冊應用程式的 GUID。

var app = PublicClientApplicationBuilder.Create(clientId)
                                        .Build();

其他 With<Parameter> 方法會設定 UI 父代、覆寫預設授權單位、指定遙測的用戶端名稱和版本、指定重新導向 URI，以及指定要使用的 HTTP 中心。例如，您可以使用 HTTP 中心來處理 Proxy，以及指定遙測和記錄。

下列各節提供有關具現化應用程式的詳細資訊。

指定父 UI、視窗或活動

在 Android 上，請先傳遞父活動，然後再進行互動式驗證。當您在 iOS 上使用訊息代理程式時，會傳遞 ViewController。方式與在 UWP 上一樣，建議您傳遞父視窗。您會在取得權杖時加以傳遞。但是，當您建立應用程式時，您也可以將回撥指定為傳回 UIParent 的委派。

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parentUi)
  .Build();

我們建議您在 Android 上使用 CurrentActivityPlugin。產生的 PublicClientApplication 建立器程式碼看起來會與這個範例類似：

// Requires MSAL.NET 4.2 or above
var pca = PublicClientApplicationBuilder
  .Create("<your-client-id-here>")
  .WithParentActivityOrWindow(() => CrossCurrentActivity.Current)
  .Build();

尋找更多應用程式建立參數

如需 PublicClientApplicationBuilder 上所有可用方法清單，請參閱方法清單。

如需 PublicClientApplicationOptions 中公開之所有選項的說明，請參閱參考文件。

適用於 iOS 和 macOS 的 MSAL 工作

當您使用適用於 iOS 和 macOS 的 MSAL 時，必須執行下列工作：

適用於 Xamarin.Android 的工作

如果您使用的是 Xamarin.Android，請執行下列工作：

如需詳細資訊，請參閱 Xamarin.Android 考量。

如需有關 Android 上瀏覽器的考慮，請參閱使用 MSAL.NET 的 Xamarin.Android 特定考量。

UWP 的工作

在 UWP 上，您可以使用公司網路。下列各節說明您應該在公司情節中完成的工作。

如需詳細資訊，請參閱使用 MSAL.NET 的 UWP 特定考量。

設定應用程式以使用訊息代理程式

在 Android 和 iOS 上，訊息代理程式會啟用：

單一登入 (SSO)：您可以對使用 Microsoft entra ID 註冊的裝置使用 SSO。使用 SSO 時，使用者不需要登入每個應用程式。
裝置識別：此設定可啟用與 Microsoft Entra 裝置相關的條件式存取原則。驗證程序會使用裝置加入工作場所時所建立的裝置憑證。
應用程式識別驗證：當應用程式呼叫訊息代理程式時，會傳遞其重新導向 URL。訊息代理程式會驗證 URL。

啟用 Xamarin 上的訊息代理程式

若要啟用 Xamarin 上的訊息代理程式，請在呼叫 PublicClientApplicationBuilder.CreateApplication 方法時使用 WithBroker() 參數。 .WithBroker() 預設設為 true。

若要啟用適用於 Xamarin.iOS 的代理驗證，請遵循本文中的 Xamarin.iOS 一節中的步驟。

針對 Android 啟用適用於 MSAL 的訊息代理程式

如需有關在 Android 上啟用訊息代理程式的詳細資訊，請參閱 Android 上的代理驗證。

啟用適用於 iOS 和 macOS 的 MSAL 訊息代理程式

預設情況下，對於適用於 iOS 和 macOS 的 MSAL 中的 Microsoft Entra 案例啟用代理驗證。

下列各節提供應用程式設定的指示，以便為適用於 Xamarin.iOS 的 MSAL 和適用於 iOS 和 macOS 的 MSAL 提供代理驗證支援。在這兩組指示中，部分步驟不同。

啟用 Xamarin iOS 的代理驗證

遵循本節中的步驟，讓 Xamarin.iOS 應用程式與 Microsoft Authenticator 應用程式交談。

步驟 1：啟用訊息代理程式支援

系統預設會停用訊息代理程式支援。您可以針對個別 PublicClientApplication 類別啟用此功能。當您透過 PublicClientApplicationBuilder 建立 PublicClientApplication 類別時，請使用 WithBroker() 參數。 WithBroker() 參數預設設定為 True。

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
                .Build();

步驟 2：更新 AppDelegate 以處理回撥

當 MSAL.NET 呼叫訊息代理程式時，訊息代理程式會接著重新呼叫應用程式。其會使用 AppDelegate.OpenUrl 方法重新呼叫。因為 MSAL 會等候來自訊息代理程式的回應，所以應用程式必須合作來重新呼叫 MSAL.NET。您可以藉由更新 AppDelegate.cs 檔案覆寫方法來設定此行為，如下列程式碼所示。

public override bool OpenUrl(UIApplication app, NSUrl url,
                             string sourceApplication,
                             NSObject annotation)
{
 if (AuthenticationContinuationHelper.IsBrokerResponse(sourceApplication))
 {
  AuthenticationContinuationHelper.SetBrokerContinuationEventArgs(url);
  return true;
 }
 else if (!AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url))
 {
  return false;
 }
 return true;
}

每次啟動應用程式時，就會叫用這個方法。這是處理來自訊息代理程式的回應，以及完成 MSAL.NET 開始之驗證程序的機會。

步驟 3：設定 UIViewController ()

若是 Xamarin iOS，您通常不需要設定物件視窗。但是在此情況下，您應該將其設定為可傳送和接收來自訊息代理程式的回應。若要設定物件視窗，請在 AppDelegate.cs 中設定 ViewController。

若要設定物件視窗，請遵循下列步驟：

在 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."

在 AcquireTokenInteractive 呼叫中，請使用 .WithParentActivityOrWindow(App.RootViewController)。傳遞您將使用之物件視窗的參考。以下是範例：

在 App.cs 中：

   public static object RootViewController { get; set; }

在 AppDelegate.cs 中：

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

在 AcquireToken 呼叫中：

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

步驟 4︰註冊 URL 配置

MSAL.NET 使用 URL 叫用訊息代理程式，然後將訊息代理程式回應傳回給應用程式。若要完成來回行程，請在 Info.plist 檔案中註冊應用程式的 URL 配置。

若要註冊應用程式的 URL 配置，請遵循下列步驟：

使用 msauth 作為 CFBundleURLSchemes 的前置詞。

將 CFBundleURLName 新增至結尾。遵循此模式：

$"msauth.(BundleId)"

在這裡，BundleId 可唯一識別裝置。例如，如果 BundleId 是 yourcompany.xforms，則 URL 配置為 msauth.com.yourcompany.xforms。

此 URL 配置將成為重新導向 URI 的一部分，可在接收到訊息代理程式的回應時，唯一識別應用程式。

 <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>

步驟 5：新增至 LSApplicationQueriesSchemes 區段

MSAL 會使用 –canOpenURL: 檢查裝置上是否已安裝訊息代理程式。在 iOS 9 中，Apple 會鎖定應用程式可以查詢的配置。

如下列程式碼範例所示，在 Info.plist 檔案的 LSApplicationQueriesSchemes 區段中新增 msauthv2：

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

適用於 iOS 和 macOS 的 MSAL 代理驗證

預設會為 Microsoft Entra 案例啟用代理驗證。

步驟 1：更新 AppDelegate 以處理回撥

當適用於 iOS 和 macOS 的 MSAL 呼叫訊息代理程式時，訊息代理程式會使用 openURL 方法重新呼叫您的應用程式。因為 MSAL 會等候來自訊息代理程式的回應，所以應用程式必須合作來重新呼叫 MSAL。如下列程式碼範例所示，您可以藉由更新 AppDelegate.m 檔案覆寫方法來設定此行為。

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [MSALPublicClientApplication handleMSALResponse:url
                                         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

        guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
            return false
        }

        return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
    }

如果您在 iOS 13 或更新版本上採用 UISceneDelegate，請改為將 MSAL 回撥放入 UISceneDelegate 的 scene:openURLContexts:。每個 URL 都只能呼叫一次 MSAL handleMSALResponse:sourceApplication:。

如需詳細資訊，請參閱 Apple 文件。

步驟 2︰註冊 URL 配置

適用於 iOS 和 macOS 的 MSAL 會使用 URL 叫用訊息代理程式，然後將訊息代理程式回應傳回給應用程式。若要完成來回行程，請在 Info.plist 檔案中註冊應用程式的 URL 配置。

若要為您的應用程式註冊配置：

使用 msauth 作為自訂 URL 配置的前置詞。
將您的搭售方案識別碼新增至配置的結尾。遵循此模式：

$"msauth.(BundleId)"

在這裡，BundleId 可唯一識別裝置。例如，如果 BundleId 是 yourcompany.xforms，則 URL 配置為 msauth.com.yourcompany.xforms。

此 URL 配置將成為重新導向 URI 的一部分，可在接收到訊息代理程式的回應時，唯一識別應用程式。請確定已為應用程式註冊格式為 msauth.(BundleId)://auth 的重新導向 URI。
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

步驟 3：新增 LSApplicationQueriesSchemes

新增 LSApplicationQueriesSchemes 以允許對 Microsoft Authenticator 應用程式的呼叫 (如果已安裝)。

注意

使用 Xcode 11 和更新版本編譯應用程式時，需要 msauthv3 配置。

以下是如何新增 LSApplicationQueriesSchemes 的範例：

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

Xamarin.Android 的代理驗證

如需有關在 Android 上啟用訊息代理程式的詳細資訊，請參閱 Xamarin.Android 上的代理驗證。

下一步

繼續本案例的下一篇文章：取得權杖。

共用方式為

設定可呼叫 Web API 的行動應用程式

支援行動應用程式的 Microsoft 程式庫

具現化應用程式

Android

iOS

Xamarin 或 UWP

具現化應用程式

指定父 UI、視窗或活動

尋找更多應用程式建立參數

適用於 iOS 和 macOS 的 MSAL 工作

適用於 Xamarin.Android 的工作

UWP 的工作

設定應用程式以使用訊息代理程式

啟用 Xamarin 上的訊息代理程式

針對 Android 啟用適用於 MSAL 的訊息代理程式

啟用適用於 iOS 和 macOS 的 MSAL 訊息代理程式

啟用 Xamarin iOS 的代理驗證

步驟 1：啟用訊息代理程式支援

步驟 2：更新 AppDelegate 以處理回撥

步驟 3：設定 UIViewController ()

步驟 4︰註冊 URL 配置

步驟 5：新增至 LSApplicationQueriesSchemes 區段

適用於 iOS 和 macOS 的 MSAL 代理驗證

步驟 1：更新 AppDelegate 以處理回撥

步驟 2︰註冊 URL 配置

步驟 3：新增 LSApplicationQueriesSchemes

Xamarin.Android 的代理驗證

下一步

意見反應

其他資源