配置调用 Web API 的移动应用

创建应用程序后，可以了解如何使用应用注册参数配置代码。 移动应用程序提供了一些与适应其创建框架相关的额外复杂性。

先决条件

• 拥有有效订阅的 Azure 帐户。 创建账户。 此帐户必须具有管理应用程序的权限。 使用以下任意一个角色注册应用程序：
  • 应用程序管理员
  • 应用程序开发人员
• 在 Microsoft Entra 管理中心注册一个新应用，并配置为仅适用于此组织目录中的帐户。 有关更多详细信息 ，请参阅注册应用程序 。 在应用程序 概述 页中记录以下值供以后使用：
  • 应用程序（客户端）ID
  • 目录（租户）ID

添加平台重定向 URI

若要将应用类型指定到应用注册，请执行以下步骤：

1. 在“管理”下，选择“身份验证”“添加平台”“iOS/macOS” 。
2. 输入你的捆绑 ID，然后选择“配置”。 将为你计算重定向 URI。

如果你偏向于手动配置重定向 URI，可以通过应用程序清单进行配置。 下面是清单的建议格式：

• iOS：msauth.<BUNDLE_ID>://auth
  • 例如，输入 msauth.com.yourcompany.appName://auth
• Android：msauth://<PACKAGE_NAME>/<SIGNATURE_HASH>
  • 可以通过 KeyTool 命令使用发布密钥或调试密钥来生成 Android 签名哈希。

启用公共客户端流

如果应用仅使用用户名-密码身份验证，则无需为应用程序注册重定向 URI。 此流将往返访问 Microsoft 标识平台。 不会在任何特定 URI 上调用你的应用程序。 但应启用公共客户端流。

若要将应用标识为公共客户端，请执行以下步骤：

1. 在“管理”下，选择“身份验证”。

2. 在“高级设置”下，对于“允许公共客户端流”，选择“是”。

3. 选择 保存 以保存更改。

支持移动应用的 Microsoft 库

以下 Microsoft 库支持移动应用：

平台	项目 GitHub	包	获取 入门	用户登录	访问 Web API	正式发布 (GA) 或 公共预览版1
Android （Java）	MSAL Android	MSAL	快速入门			GA
Android （Kotlin）	MSAL Android	MSAL	—			GA
iOS （Swift/Obj-C）	适用于 iOS 和 macOS 的 MSAL	MSAL	教程			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 令牌缓存的行为。

UWP

本部分介绍如何实例化 UWP 应用的应用程序。

实例化应用程序

在 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 时，需要执行以下任务：

• 实现 openURL 回调
• 启用密钥链访问组
• 自定义浏览器和 WebView

UWP 的任务

在 UWP 上，可以使用企业网络。 以下部分说明应在企业方案中完成的任务。

有关详细信息，请参阅 MSAL.NET 的 UWP 特定注意事项。

将应用程序配置为使用中介

在 Android 和 iOS 上，中介可以实现：

• 单一登录 (SSO)：可以对已注册到 Microsoft Entra ID 的设备使用 SSO。 使用 SSO 时，用户无需登录到每个应用程序。
• 设备标识：此设置启用与 Microsoft Entra 设备相关的条件访问策略。 身份验证过程使用将设备加入工作区时创建的设备证书。
• 应用程序标识验证：应用程序在调用中介时会传递其重定向 URL。 然后中介验证该 URL。

为用于 iOS 和 macOS 的 MSAL 启用中介

默认已为适用于 iOS 和 macOS 的 MSAL 中的 Microsoft Entra 方案启用中介身份验证。

以下部分提供了为 iOS 和 macOS 配置应用程序以支持代理身份验证的说明。 这两套说明中的某些步骤有所不同。

适用于 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 回调放入 scene:openURLContexts: 的 UISceneDelegate 中。 只能对每个 URL 调用 MSAL handleMSALResponse:sourceApplication: 一次。

有关详细信息，请参阅 Apple 文档。

步骤 2：注册 URL 方案

适用于 iOS 和 macOS 的 MSAL 使用 URL 调用中介，然后将中介响应返回到应用。 若要完成往返过程，请在 Info.plist 文件中注册应用的 URL 方案。

为应用注册方案：

1. 使用 msauth 作为自定义 URL 方案的前缀。

2. 将捆绑标识符添加到方案的末尾。 遵循以下模式：

   $"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 应用（如果已安装）。

下面是如何添加 LSApplicationQueriesSchemes 的示例：

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

后续步骤

转到此方案中的下一篇文章：获取令牌。