配置调用 Web API 的移动应用

项目
07/28/2024

创建应用程序后，可以了解如何使用应用注册参数配置代码。将移动应用程序装入其创建框架时存在一定的复杂性。

支持移动应用的 Microsoft 库

以下 Microsoft 库支持移动应用：

平台	项目 GitHub	包	获取 started	正式发布 (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 等新式框架。阅读宣布即将弃用 MSAL.NET for Xamarin 和 UWP 中有关弃用的详细信息。

实例化应用程序

在 Xamarin 或 UWP 中，实例化应用程序的最简单方法是使用以下代码。在此代码中，ClientId 是注册的应用的 GUID。

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

其他 With<Parameter> 方法可以设置 UI 父级、重写默认的颁发机构、指定遥测的客户端名称和版本、指定重定向 URI 以及指定要使用的 HTTP 工厂。例如，可以使用 HTTP 工厂来处理代理以及指定遥测和日志记录。

以下部分提供了有关实例化应用程序的详细信息。

指定父 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 部分中的步骤。

为用于 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 方案，请执行以下步骤：

为 CFBundleURLSchemes 加上 msauth 前缀。

将 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 锁定了应用程序可以查询的方案。

将 msauthv2 添加到 Info.plist 文件的 LSApplicationQueriesSchemes 节，如以下代码示例所示：

<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 上启用中介

为用于 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 的中介身份验证

后续步骤

其他资源