30DaysMSGraph – Upgrading to MSAL .NET v4

Brian T. Jackett

List of all posts in the #30DaysMSGraph series

We wrapped up the #30DaysMSGraph series in Nov 2018.  Since that time there have been a few updates to the Microsoft Graph SDK as well as the Microsoft Authentication Library (MSAL).  Notably MSAL for .NET and JavaScript are now generally available (GA) with v3.0.8 and MSAL.NET 4.0.0 is now available as well.  This is a good opportunity to upgrade the samples in the dotnetcore-console-sample repo to leverage MSAL .NET v4.

Breaking Changes with MSAL .NETv3

MSAL .NET v3 (and consequently v4 also) introduces a number of breaking changes when upgrading from MSAL .NET v2.  Thankfully these changes (ex. process to instantiate a public or confidential client application, see screenshot below) are surfaced as compiler warnings (v3) or errors (v4) with additional information on how to resolve them.  Since the projects in the dotnetcore-console-sample repo were originally based on MSAL .NET v2.x we’ll review the changes that impacted these samples.  To avoid compiler errors when upgrading MSAL .NET, you may want to target v3.x explicitly while addressing any necessary updates to the codebase.  Please watching the March 2019 Office Hours for Microsoft Identity Platform and read the documentation mentioned earlier to understand how and why changes were made as well as the future plans for MSAL v4 and beyond.

Overview

The primary changes that need to be made include:

  1. Instantiate client application – leverage builder pattern
  2. Base class for client application – implement an interface
  3. Acquire token method – replace AcquireToken_xxx_Async(…) with AcquireToken_xxx_().ExecuteAsync()

Instantiate client application

In MSAL .NET v2, when you instantiated either a ConfidentialClientApplication or PublicClientApplication there were multiple overloads and parameters had to be specified inline.  Now it is possible to specify parameters through a fluent syntax as well as pulling from a file / configuration of your own.  In the Program.cs of base-console-sample the syntax changes from

var cca = new ConfidentialClientApplication(clientId, authority, redirectUri, new ClientCredential(clientSecret), null, null);

to

var cca = ConfidentialClientApplicationBuilder.Create(clientId)
             .WithAuthority(authority)
             .WithRedirectUri(redirectUri)
             .WithClientSecret(clientSecret)
             .Build();

Base class for client application

In MSAL .NET v2, client application leveraged base classes of ConfidentialClientApplication or PublicClientApplication.  These are now shifted to interfaces of IConfidentialClientApplication or IPublicClientApplication.  In MsalAuthenticationProvider.cs of base-console-sample the private member of type ConfidentialClientApplication changes from

private ConfidentialClientApplication _clientApplication;
public MsalAuthenticationProvider(ConfidentialClientApplication clientApplication, string[] scopes)

to

private IConfidentialClientApplication _clientApplication;
public MsalAuthenticationProvider(IConfidentialClientApplication clientApplication, string[] scopes)

Acquire token method

In MSAL .NET v2, the ConfidentialClientApplication class had numerous methods for acquiring a token and multiple overloads per method with the many optional parameters.  Similar to the new fluent syntax for ConfidentialClientApplicationBuilder, it is now possible to specify required parameters in the primary AcquireToken_xxx_() method with optional parameters in follow-on method calls with a final call to ExecuteAsync().  In MsalAuthenticationProvider.cs of base-console-sample the token acquisition changes from

authResult = await _clientApplication.AcquireTokenForClientAsync(_scopes);

to

authResult = await _clientApplication.AcquireTokenForClient(_scopes)
                     .ExecuteAsync();

Conclusion

The above changes were the minimal amount of code changes required to upgrade to MSAL .NET v3 or v4.  Future planned changes include adopting ConfidentialClientApplicationBuilder.CreateWithOptions() to provide additional flexibility.  When choosing which version of MSAL .NET to implement read the deprecation plans and plan accordingly.  We’re in the process of updating all of the dotnetcore-console-sample code samples and documentation to leverage MSAL .NET v4.  If you find any samples or docs that are incorrect or do not work as expected please file an issue.

Feedback usabilla icon