System Browser on .Net Core

Note: this feature is available from version 4.0.0 on .Net Core and from version 4.1.0 on .Net Classic and .Net Standard. B2C does not currently support this mode of authentication.

Embedded vs System Web UI

MSAL is a multi-framework library and has framework specific code to host a browser in a UI control (e.g. on .Net Classic it uses WinForms, on Xamarin it uses native mobile controls etc.). This is called embedded web ui. Alternatively, MSAL is also able to kick off the system OS browser.

Generally, we recommend that you use the platform default, and this is typically the system browser. The system browser is better at remembering the users that have logged in before. If you need to change this behavior, use WithUseEmbeddedWebView(bool)

System Browser Experience

On .NET Core, MSAL will start the system browser as a separate process. MSAL does not have control over this browser, but once the user finishes authentication, the web page is redirected in such a way that MSAL can intercept the Uri.

You can also configure apps written for .NET Classic to use this browser, by specifying

await pca.AcquireTokenInteractive(s_scopes)
         .WithUseEmbeddedWebView(false)

MSAL cannot detect if the user navigates away or simply closes the browser. Apps using this technique are encouraged to define a timeout (via CancellationToken). We recommend a timeout of at least a few minutes, to take into account cases where the user is prompted to change password or perform 2FA.

How to use the Default OS Browser

MSAL needs to listen on on http://localhost:port and intercept the code that AAD sends when the user is done authenticating.

To achieve this:

1. During app registration, configure http://localhost as a redirect uri (not currently supported by B2C)
2. When you construct your PubliClientApplication, specify this redirect uri:

IPublicClientApplication pca = PublicClientApplicationBuilder
                            .Create("<CLIENT_ID>")
                             // or use a known port if you wish "http://localhost:1234"
                            .WithRedirectUri("http://localhost")  
                            .Build();

Note: If you configure http://localhost, internally MSAL will find a random open port and use it.

Linux and MAC

On Linux, MSAL will open the default OS browser using the xdg-open tool. To troubleshoot, run the tool from a terminal e.g. xdg-open "https://www.bing.com"
On Mac, the browser is opened by invoking open <url>

Customizing the experience

Note: customization is available from MSAL 4.1.0 onward

MSAL is able to respond with an HTTP message when a token is received or in case of error. You can display an HTML message or redirect to an url of your choice:

var options = new SystemWebViewOptions() 
{
    HtmlMessageError = "<p> An error occured: {0}. Details {1}</p>",
    BrowserRedirectSuccess = new Uri("https://www.microsoft.com"); 
}
 
await pca.AcquireTokenInteractive(s_scopes)
         .WithUseEmbeddedWebView(false)
         .WithSystemWebViewOptions(options)
         .ExecuteAsync();
                           

Opening a specific browser (Experimental)

You may customize the way MSAL opens the browser. For example instead of using whatever browser is the default, you can force open a specific browser:

var options = new SystemWebViewOptions() 
{
    OpenBrowserAsync = SystemWebViewOptions.OpenWithEdgeBrowserAsync
}