如何:自定义 iOS/macOS 的浏览器和 WebViewHow to: Customize browsers and WebViews for iOS/macOS

完成交互式身份验证需要使用 Web 浏览器。A web browser is required for interactive authentication. 在 iOS 上,Microsoft 身份验证库 (MSAL) 默认使用系统 Web 浏览器(可能显示在应用的顶部)执行交互式身份验证,以将用户登录。On iOS, the Microsoft Authentication Library (MSAL) uses the system web browser by default (which might appear on top of your app) to do interactive authentication to sign in users. 使用系统浏览器的好处是可与其他应用程序和 Web 应用程序共享单一登录 (SSO) 状态。Using the system browser has the advantage of sharing the Single Sign ON (SSO) state with other applications and with web applications.

可以通过将配置自定义为其他用于显示 Web 内容的选项来更改体验,例如:You can change the experience by customizing the configuration to other options for displaying web content, such as:

仅对 iOS 而言:For iOS only:

对于 iOS 和 macOS:For iOS and macOS:

适用于 macOS 的 MSAL 仅支持 WKWebViewMSAL for macOS only supports WKWebView.

系统浏览器System browsers

对于 iOS,ASWebAuthenticationSessionSFAuthenticationSessionSFSafariViewController 被视为系统浏览器。For iOS, ASWebAuthenticationSession, SFAuthenticationSession, and SFSafariViewController are considered system browsers. 一般情况下,系统浏览器将与 Safari 浏览器应用程序共享 Cookie 和其他网站数据。In general, system browsers share cookies and other website data with the Safari browser application.

默认情况下,MSAL 会动态检测 iOS 版本,并选择适用于该版本的建议系统浏览器。By default, MSAL will dynamically detect iOS version and select the recommended system browser available on that version. 在 iOS 12+ 上,系统浏览器为 ASWebAuthenticationSessionOn iOS 12+ it will be ASWebAuthenticationSession.

版本Version Web 浏览器Web browser
iOS 12+iOS 12+ ASWebAuthenticationSessionASWebAuthenticationSession
iOS 11iOS 11 SFAuthenticationSessionSFAuthenticationSession
iOS 10iOS 10 SFSafariViewControllerSFSafariViewController

开发人员还可为 MSAL 应用选择不同的系统浏览器:Developers can also select a different system browser for MSAL apps:

  • SFAuthenticationSessionASWebAuthenticationSession 在 iOS 11 中的版本。SFAuthenticationSession is the iOS 11 version of ASWebAuthenticationSession.
  • SFSafariViewController 更通用,提供用于浏览 Web 的接口,并且还可用于登录。SFSafariViewController is more general purpose and provides an interface for browsing the web and can be used for login purposes as well. 在 iOS 9 和10中,Cookie 和其他网站数据将与 Safari 共享 -- 但 iOS 11 和更高版本中不提供这种共享。In iOS 9 and 10, cookies and other website data are shared with Safari--but not in iOS 11 and later.

应用中浏览器In-app browser

WKWebView 是显示 Web 内容的应用中浏览器。WKWebView is an in-app browser that displays web content. 它不与其他 WKWebView 实例或 Safari 浏览器共享 Cookie 或网站数据。It doesn't share cookies or web site data with other WKWebView instances, or with the Safari browser. WKWebView 是同时适用于 iOS 和 macOS 的跨平台浏览器。WKWebView is a cross-platform browser that is available for both iOS and macOS.

所用浏览器共享 Cookie 的方式会影响 SSO 体验。The browser you use impacts the SSO experience because of how they share cookies. 下表汇总了每个浏览器的 SSO 体验。The following tables summarize the SSO experiences per browser.

技术Technology 浏览器类型Browser Type iOS 可用性iOS availability macOS 可用性macOS availability 共享 Cookie 和其他数据Shares cookies and other data MSAL 可用性MSAL availability SSOSSO
ASWebAuthenticationSessionASWebAuthenticationSession 系统System iOS12 和更高版本iOS12 and up macOS 10.15 和更高版本macOS 10.15 and up Yes 仅限 iOSiOS only 具有 Safari 实例w/ Safari instances
SFAuthenticationSessionSFAuthenticationSession 系统System iOS11 和更高版本iOS11 and up 不适用N/A Yes 仅限 iOSiOS only 具有 Safari 实例w/ Safari instances
SFSafariViewControllerSFSafariViewController 系统System iOS11 和更高版本iOS11 and up 不适用N/A No 仅限 iOSiOS only 否**No**
SFSafariViewControllerSFSafariViewController 系统System iOS10iOS10 不适用N/A Yes 仅限 iOSiOS only 具有 Safari 实例w/ Safari instances
WKWebViewWKWebView 应用中In-app iOS8 和更高版本iOS8 and up macOS 10.10 和更高版本macOS 10.10 and up No iOS 和 macOSiOS and macOS 否**No**

** 要正常进行 SSO,需要在应用之间共享令牌。** For SSO to work, tokens need to be shared between apps. 这需要使用令牌缓存或中介应用程序,例如适用于 iOS 的 Microsoft Authenticator。This requires a token cache, or broker application, such as Microsoft Authenticator for iOS.

更改请求的默认浏览器Change the default browser for the request

可以根据 UX 要求使用应用中浏览器或特定的系统浏览器,只需在 MSALWebviewParameters 中更改以下属性即可:You can use an in-app browser, or a specific system browser depending on your UX requirements, by changing the following property in MSALWebviewParameters:

@property (nonatomic) MSALWebviewType webviewType;

按交互式请求进行更改Change per interactive request

可以通过更改 MSALInteractiveTokenParameters.webviewParameters.webviewType 属性,然后将其传递给 acquireTokenWithParameters:completionBlock: API,将每个请求配置为替代默认浏览器。Each request can be configured to override the default browser by changing the MSALInteractiveTokenParameters.webviewParameters.webviewType property before passing it to the acquireTokenWithParameters:completionBlock: API.

此外,MSAL 还支持通过设置 MSALInteractiveTokenParameters.webviewParameters.customWebView 属性来传入自定义 WKWebViewAdditionally, MSAL supports passing in a custom WKWebView by setting the MSALInteractiveTokenParameters.webviewParameters.customWebView property.

例如:For example:

Objective-CObjective-C

UIViewController *myParentController = ...;
WKWebView *myCustomWebView = ...;
MSALWebviewParameters *webViewParameters = [[MSALWebviewParameters alloc] initWithParentViewController:myParentController];
webViewParameters.webviewType = MSALWebviewTypeWKWebView;
webViewParameters.customWebview = myCustomWebView;
MSALInteractiveTokenParameters *interactiveParameters = [[MSALInteractiveTokenParameters alloc] initWithScopes:@[@"myscope"] webviewParameters:webViewParameters];
    
[app acquireTokenWithParameters:interactiveParameters completionBlock:completionBlock];

SwiftSwift

let myParentController: UIViewController = ...
let myCustomWebView: WKWebView = ...
let webViewParameters = MSALWebviewParameters(parentViewController: myParentController)
webViewParameters.webviewType = MSALWebviewType.wkWebView
webViewParameters.customWebview = myCustomWebView
let interactiveParameters = MSALInteractiveTokenParameters(scopes: ["myscope"], webviewParameters: webViewParameters)

app.acquireToken(with: interactiveParameters, completionBlock: completionBlock)

如果使用自定义 webview,则会使用通知来指示显示的 Web 内容的状态,例如:If you use a custom webview, notifications are used to indicate the status of the web content being displayed, such as:

/*! Fired at the start of a resource load in the webview. The URL of the load, if available, will be in the @"url" key in the userInfo dictionary */
extern NSString *MSALWebAuthDidStartLoadNotification;

/*! Fired when a resource finishes loading in the webview. */
extern NSString *MSALWebAuthDidFinishLoadNotification;

/*! Fired when web authentication fails due to reasons originating from the network. Look at the @"error" key in the userInfo dictionary for more details.*/
extern NSString *MSALWebAuthDidFailNotification;

/*! Fired when authentication finishes */
extern NSString *MSALWebAuthDidCompleteNotification;

/*! Fired before ADAL invokes the broker app */
extern NSString *MSALWebAuthWillSwitchToBrokerApp;

选项Options

MSAL 支持的所有 Web 浏览器类型都在 MSALWebviewType 枚举中声明All MSAL supported web browser types are declared in the MSALWebviewType enum

typedef NS_ENUM(NSInteger, MSALWebviewType)
{
#if TARGET_OS_IPHONE
    // For iOS 11 and up, uses AuthenticationSession (ASWebAuthenticationSession
    // or SFAuthenticationSession).
    // For older versions, with AuthenticationSession not being available, uses
    // SafariViewController.
    MSALWebviewTypeDefault,
    
    // Use SFAuthenticationSession/ASWebAuthenticationSession
    MSALWebviewTypeAuthenticationSession,
    
    // Use SFSafariViewController for all versions.
    MSALWebviewTypeSafariViewController,
    
#endif
    // Use WKWebView
    MSALWebviewTypeWKWebView,
};

后续步骤Next steps

详细了解身份验证流和应用程序方案Learn more about Authentication flows and application scenarios