配置调用 Web API 的移动应用
创建应用程序后,可以了解如何使用应用注册参数配置代码。 将移动应用程序装入其创建框架时存在一定的复杂性。
支持移动应用的 Microsoft 库
以下 Microsoft 库支持移动应用:
平台 | 项目 GitHub |
包 | 获取 started |
用户登录 | 访问 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 | ||
Xamarin (.NET) | MSAL.NET | Microsoft.Identity.Client | — | GA |
1 联机服务通用许可条款适用于公共预览版中的库。
实例化应用程序
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 部分中的步骤。
为用于 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 方案,请执行以下步骤:
为
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 上的中介身份验证。
后续步骤
转到此方案中的下一篇文章:获取令牌。