Customizing Browsers and WebViews

Summary

MSAL for iOS supports multiple choices in displaying web content.

The list of the supported classes and views are:

• ASWebAuthenticationSession
• SFAuthenticationSession
• SFSafariViewController
• WKWebView.

System browsers

ASWebAuthenticationSession, SFAuthenticationSession, SFSafariViewController are considered system browsers. In general, this type of browsers share cookies and other website data with Safari - other instances or the Safari browser application.

ASWebAuthenticationSession replaces SFAuthenticationSession, which has been available since iOS11. This is a class recommended to show login between Safari and an app.

SFSafariViewController is a more general-purpose that provides an interface for browsing the web, and can be used for login purposes as well. In iOS 9 and 10, cookies and other website data are shared with Safari, but does not in iOS 11 and later.

Local browsers

WKWebView is an in-app browser that displays web content. This does not share cookies nor web site data with other instances or Safari.

Cookie share, and SSO implications

Technology	Type	Availability	Shared Cookies and other data	SSO
ASWebAuthenticationSession	System	iOS12	Yes	w/ Safari instances
SFAuthenticationSession	System	iOS11	Yes	w/ Safari instances
SFSafariViewController	System	iOS11 and up	No	No**
SFSafariViewController	System	iOS10	Yes	w/ Safari instances
WKWebView	Local	iOS9 and up	No	No**

** To achieve SSO, token cache or a broker application needs to be used.

By default, MSAL for iOS uses system web browser

By default, the library will use system web browser as following:

• ASWebAuthenticationSession for iOS12
• SFAuthenticationSession for iOS11
• SFSafariViewController for iOS9 and iOS10

Developer Options

As a developer, you can choose to change the behavior to use local browser, or a specific system browser depending on the UX requirements.

Change default behavior

Change settings in MSALGlobalConfig.defaultWebviewType:

MSALGlobalConfig.defaultWebviewType = MSALWebviewTypeWKWebView;

Changing per interactive request

Request can override the default behavior by setting webviewType in MSALInteractiveTokenParameters before calling acquireTokenWithParameters:completionBlock: method.

Additionally, MSAL supports a custom WKWebView to be passed in by setting MSALInteractiveTokenParameters's customWebView property.

If custom webview is used, 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

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