Skip to content

CustomWebUi

Bogdan Gavril edited this page Aug 5, 2019 · 9 revisions

This article is about MSAL.NET 3.x. If you are interested in MSAL.NET 2.x go to Acquiring tokens interactively in MSAL 2.x

Create your own Web UI

MSAL provides Web UI implementations for most platforms, but there are still cases where may want to host the browser yourself:

  • platforms not explicitly covered by MSAL, e.g. Blazor, Unity, Mono on desktop
  • you want to UI test your application and want to use an automated browser that can be used with Selenium
  • the browser and the app running MSAL are in separate processes

To achieve this, MSAL will gives the developer a start Url, which needs to displayed in a browser of choice so that the end-user can enter his username etc. Once authentication completes, the developer needs to pass back to MSAL the end Url, which contains a code. The end Url host is always the redirectUri which can be customized. To intercept the end Url you can:

  • monitor browser redirects until the redirect Url is hit OR
  • have the browser redirect to a socket to which you listen to

WithCustomWebUi is an extensibility point

WithCustomWebUi is an extensibility point that allows you provide your own UI in public client applications, and to let the user go through the /Authorize endpoint of the identity provider and let them sign-in and consent. MSAL.NET will then be able to redeem the authentication code and get a token.

It's used in Visual Studio Electron applications (for instance VS Feedback) to provide the web interaction. The Electron app can display the browser, while MSAL runs as part of Visual Studio to maintain the user cache. You can also use it if you want to provide UI automation.

Note that, in public client applications, MSAL.NET leverages the PKCE standard (RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients) to ensure that security is respected: Only MSAL.NET can redeem the code.

How to use WithCustomWebUi

To leverage this you need to:

  1. Implement the ICustomWebUi interface (See here. You'll basically need to implement a single method AcquireAuthorizationCodeAsync accepting the authorization code URL (computed by MSAL.NET), letting the user go through the interaction with the identity provider, and then returning back the URL by which the identity provider would have called your implementation back (including the authorization code). In case of issues, your implementation should throw a MsalExtensionException exception in order to nicely cooperate with MSAL.

  2. In your AcquireTokenInteractive call you can use .WithCustomUI() modifier passing the instance of your custom web UI

using Microsoft.Identity.Client.Extensions;

 result = await app.AcquireTokenInteractive(scopes)
                   .WithCustomWebUi(yourCustomWebUI)
                   .ExecuteAsync();
 ```

Examples of implementation of ICustomWebUi in test automation - SeleniumWebUI

We have rewritten our UI tests to leverage this extensibility mechanism. In case you are interested you can have a look at the SeleniumWebUI class in the MSAL.NET source code

Getting started with MSAL.NET

Acquiring tokens

Web Apps / Web APIs / daemon apps

Desktop/Mobile apps

Advanced topics

FAQ

Other resources

Clone this wiki locally