How-To: Get Started with MSAL Authentication

MsalAuthenticationProvider allows your users to sign in using their Microsoft identities. It wraps the MSAL library from Microsoft into an implementation of IAuthenticationProvider. This tutorial will use MSAL authorization to validate user credentials.

Step-by-step

Important

This guide assumes you used the template wizard or dotnet new unoapp to create your solution. If not, it is recommended that you follow the Creating an application with Uno.Extensions documentation to create an application from the template.

1. Prepare for MSAL authentication

• For this type of authentication, the application must be registered with the Microsoft identity platform. For more information, see Register an application with the Microsoft identity platform.

• The identity provider will provider you with a client ID and guidance on scopes to use.

• Add AuthenticationMsal to the <UnoFeatures> property in the Class Library (.csproj) file.

  <UnoFeatures>
      Material;
  +   AuthenticationMsal;
      Toolkit;
      MVUX;
  </UnoFeatures>
  

2. Set up MSAL authentication

• Use the UseAuthentication() extension method to configure the IHostBuilder to use an authentication provider. In our case, we will be using the MsalAuthenticationProvider.

  private IHost Host { get; set; }
  
  protected override void OnLaunched(LaunchActivatedEventArgs args)
  {
      var builder = this.CreateBuilder(args)
          .Configure(host =>
          {
              host
              .UseAuthentication(builder =>
              {
                  // Add the authentication provider here
              });
          });
      ...
  }
  

• Add the MsalAuthenticationProvider using the AddMsal() extension method which configures the IAuthenticationBuilder to use it.

  private IHost Host { get; set; }
  
  protected override void OnLaunched(LaunchActivatedEventArgs args)
  {
      var builder = this.CreateBuilder(args)
          .Configure(host =>
          {
              host
              .UseAuthentication(builder =>
              {
                  builder.AddMsal();
              });
          });
      ...
  }
  

• The IAuthenticationBuilder is responsible for managing the lifecycle of the associated provider that was built.

• Because it is configured to use MSAL, the user will eventually be prompted to sign in to their Microsoft account when they use your application. MsalAuthenticationProvider will then store the user's access token in credential storage. The token will be automatically refreshed when it expires.

3. Configure the provider

• While MsalAuthenticationProvider is added using the AddMsal() extension method, you will need to add a configuration section to your appsettings.json file with your client ID and scopes.

  The following example shows how to configure the provider using the default section name:

  {
    "Msal": {
      "ClientId": "161a9fb5-3b16-487a-81a2-ac45dcc0ad3b",
      "Scopes": [ "Tasks.Read", "User.Read", "Tasks.ReadWrite" ]
    }
  }
  

  This configuration can also be done in the root App.cs file:

  private IHost Host { get; set; }
  
  protected override void OnLaunched(LaunchActivatedEventArgs args)
  {
      var builder = this.CreateBuilder(args)
          .Configure(host =>
          {
              host
              .UseAuthentication(builder =>
              {
                  builder.AddMsal(msal =>
                      msal
                      .Builder(msalBuilder => 
                          msalBuilder.WithClientId("161a9fb5-3b16-487a-81a2-ac45dcc0ad3b"))
                      .Scopes(new[] { "Tasks.Read", "User.Read", "Tasks.ReadWrite" })
                  );
              });
          });
      ...
  }
  

  Warning

  A ClientId of GUID format is required for MSAL Authentication to work. You can specify it in the appsettings.json file, or in the code itself. If the ClientId cannot be found, the app will crash with the following error:

  Exception thrown: 'Microsoft.Identity.Client.MsalClientException' in Microsoft.Identity.Client.dll
  No ClientId was specified.
  

4. Use the provider in your application

• Update the MainPage to include a Button labeled to sign in with Microsoft.

  <Page
      x:Class="MyApp.MainPage"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:local="using:MyApp"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      mc:Ignorable="d">
  
      <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
          <Button x:Name="SignInButton" Content="Sign in with Microsoft" Command="{x:Bind ViewModel.Authenticate}" />
      </Grid>
  </Page>
  

• Because the IAuthenticationService instance will be injected into our view models, we can now update the MainViewModel to include a Command that will use that service to sign in a user.

  public class MainViewModel : ObservableObject
  {
      private readonly IAuthenticationService _authenticationService;
  
      public MainViewModel(IAuthenticationService authenticationService)
      {
          _authenticationService = authenticationService;
          Authenticate = new AsyncRelayCommand(AuthenticateAsync);
      }
  
      public ICommand Authenticate { get; }
  
      private async Task AuthenticateAsync()
      {
          await _authenticationService.LoginAsync(/* ... */);
      }
  }
  

• Finally, we can run the application and sign in with our Microsoft account. The user will be prompted to sign in to their Microsoft account when they tap the button in the application.

• MsalAuthenticationProvider will then store the user's access token in credential storage. The token will be automatically refreshed when it expires.