MSAL.NET uses web browser
| Framework | Embedded | System | Default |
|---|---|---|---|
| .NET Classic | Yes | Yes^ | Embedded |
| .NET Core | No | Yes^ | System |
| .NET Standard | No | No | NONE |
| UWP | Yes | No | Embedded |
| Xamarin.Android | Yes | Yes | System |
| Xamarin.iOS | Yes | Yes | System |
| Xamarin.Mac | Yes | Yes^ | Embedded |
^ Requires "http://localhost" redirect URI
On Xamarin.Android and Xamarin.iOS, MSAL is able to use app specific urls to intercept a code from AAD.
- Web browsers are required for interactive authentication
- By default, MSAL.NET supports the system web browser on Xamarin.iOS Xamarin.Android and also on .NET Core, .NET Standard and .NET Classic see details
- But you can also enable the Embedded Web browser depending on your requirements (UX, need for SSO, security) in Xamarin.iOS and Xamarin.Android apps.
- And you can even choose dynamically which web browser to use based on the presence of Chrome or a browser supporting Chrome custom tabs in Android.
One important understanding with authentication libraries and Azure AD is that, when acquiring a token interactively, the content of the dialog box is not provided by the library, but by the STS (Security Token Service). The authentication endpoint sends back some HTML and JavaScript that control the interaction, and it's rendered in a web browser or web control. Allowing the STS to handle the HTML interaction has many advantages:
- The password (if one was typed) is never stored by the application, nor the authentication library.
- Enabling redirections to other identity providers (for instance login-in with a work school account or a personal account with MSAL, or with a social account with Azure AD B2C).
- Letting the STS control conditional access, for instance by having the user do multiple factor authentication (MFA) during this authentication phase (entering a Windows Hello pin, or being called on their phone, or on an authentication app on their phone). In cases where multi factor authentication is required and the user has not set it up yet, they can even set it up just in time in the same dialog: they enter their mobile phone number, and are guided to install an authentication application and scan a QR tag to add their account. This server driven interaction is a great experience!
- Letting the user change their password in this same dialog when the password has expired (providing additional fields for the old password and the new password).
- Enabling branding of the tenant, or the application (images) controlled by the Azure AD tenant admin / application owner.
- Enabling the users to consent to let the application access resources / scopes in their name just after the authentication.
Please see System Browser on .NET Core for details
MSAL.NET leverages by default the system web browser for Xamarin iOS and Xamarin Android applications. On iOS, it even choses the web view to use depending on the version of the Operating System (iOS12, iOS11, and earlier)
Using the system browser has the significant advantage of sharing the SSO state with other applications and with web applications without needing a broker (Company portal / Authenticator). The system browser was used, by default, in the MSAL.NET for the Xamarin iOS and Xamarin Android platforms because, on these platforms, the system web browser occupies the whole screen, and the user experience is better. The system web view is not distinguishable from a dialog. On iOS, though, the user might have to give consent for the browser to call back the application, which can be annoying.
For desktop applications, however, launching a System Webview leads to a sub-par user experience, as the user sees the browser, where they might already have other tabs opened. And when authentication has happened, the users gets a page asking them to close this window. If the user does not pay attention, they can close the entire process (including other tabs, which are unrelated to the authentication). Leveraging the system browser on desktop would also require opening local ports and listening on them, which might require advanced permissions for the application. You, as a developer, user, or administrator, might be reluctant about this requirement.
MSAL.NET also supports using the embedded webview option. Note that for ADAL.NET, embedded webview is the only option supported. As a developer using MSAL.NET targeting Xamarin, you may choose to use either embedded webviews or system browsers. This is your choice depending on the user experience and security concerns you want to target, but it's not recommended for B2C as some integrated identity providers don't allow it.
Interactive sign-in with MSAL.NET using the Embedded Webview:
Interactive sign-in with MSAL.NET using the System Browser:
Note: The way you chose between the system browser and the embedded webview will change some time in the near future (before official release).
As a developer using MSAL.NET, you have several options for displaying the interactive dialog from STS:
- System browser. The system browser is set by default in the library. If using Android, please see system browsers with specific information about which browsers are supported for authentication. Note that when using system browser in Android, we recommend the device have a browser which supports Chrome custom tabs, otherwise, authentication may fail. For more information about these issues, read the section on Android system browsers.
- Embedded webview. Enables you to specify if you want to force the usage of an embedded web view. For more details see Usage of Web browsers
result = await app.AcquireTokenInteractive(scopes)
.WithUseEmbeddedWebView(true)
.ExecuteAsync();AcquireTokenInteractive has one specific optional parameter enabling it to specify, for platforms supporting it, the parent UI (window in Windows, Activity in Android). This parent UI is specified using .WithParentActivityOrWindow(). The UI dialog will typically be centered on that parent. On Android the parent activity is a mandatory parameter.
// Android
WithParentActivityOrWindow(Activity activity)
// iOS
WithParentActivityOrWindow(IUIViewController viewController)If you want to use the system web browser to enable SSO with the apps running in the browser, but are worried about the user experience for Android devices not having a browser with custom tab support, you have the option to decide by calling IsSystemWebViewAvailable. This method returns true if the PackageManager detects custom tabs and false if they are not detected on the device.
Based on the value returned by this method, and your requirements, as the developer, you can make a decision:
- You can return a custom error message to the user. For example: "Please install Chrome to continue with authentication" -OR-
- You can fallback to the embedded webview option and launch the UI as an embedded webview
The code below shows how you would do the later:
bool useEmbeddedWebView = !app.IsSystemWebViewAvailable;
var authResult = AcquireTokenInteractive(scopes)
.WithParentActivityOrWindow(parentActivity)
.WithEmbeddedWebView(useEmbeddedWebView)
.ExecuteAsync();For .NET Core, an embedded browser is not available because .NET Core does not provide UI yet.