0.3.0 preview - mattchenderson/microsoft-identity-web GitHub Wiki

How to migrate from 0.2.x

The public API changed in the 0.3.0-preview based on your feedback. We had three objective:

finalize the branding (ensure that the top level method in Startup.cs contains MicrosoftIdentity, whereas they were previously containing Microsoft, which was overloaded: ASP.NET Core had a Microsoft (meaning personal accounts) authentication already.
Express what the method does. For instance we used to have WebAppCallsWebApi, whereas it was really enabling calling an API by exposing the Token acquisition service.
Simplify the API and avoid you to have to repeat the same information (with the risk of making errors). The API is now a kind of funnel, where, when choosing an override, you are then only presented by IntelliSense with the override that make sense. For instance if you start by using an override of AddMicrosoftIdentityWebApp with delegates, you can only use an override of EnableTokenAcquisitionToCallDownstreamApi.

Before	After
services.AddMicrosoftWebAppAuthentication()	services.AddMicrosoftIdentityWebAppAuthentication()
services.AddAuthentication().AddMicrosoftWebApp()	services.AddAuthentication().AddMicrosoftIdentityWebApp()
services.AddMicrosoftWebApiAuthentication()	services.AddMicrosoftIdentityWebApiAuthentication()
services.AddAuthentication().AddMicrosoftWebApi()	services.AddAuthentication().AddMicrosoftIdentityWebApi()
services.AddAuthentication().AddMicrosoftWebApp().AddMicrosoftWebAppCallsWebApi()	services.AddAuthentication().AddMicrosoftIdentityWebApp().EnableTokenAcquisitionToCallDownstreamApi()
services.AddAuthentication().AddMicrosoftWebApi().AddMicrosoftWebApiCallsWebApi()	services.AddAuthentication().AddMicrosoftIdentityWebApi().EnableTokenAcquisitionToCallDownstreamApi()
services.AddInMemoryTokenCaches()	.EnableTokenAcquisitionToCallDownstreamApi().AddInMemoryTokenCaches()
services.AddDistributedTokenCaches()	.EnableTokenAcquisitionToCallDownstreamApi().AddDistributedTokenCaches()
services.AddSessionTokenCaches()	.EnableTokenAcquisitionToCallDownstreamApi().AddSessionTokenCaches()
services.AddMicrosoftGraph()	.EnableTokenAcquisitionToCallDownstreamApi().AddMicrosoftGraph()
services.AddDownstreamApiService()	.EnableTokenAcquisitionToCallDownstreamApi().AddDownstreamApi()

Web apps

Simple with the configuration

  services.AddMicrosoftIdentityWebAppAuthentication(Configuration)
          .EnableTokenAcquisitionToCallDownstreamApi()
          .AddInMemoryTokenCaches();

Simple with the configuration section

 services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
         .AddMicrosoftIdentityWebApp(Configuration.GetSection("AzureAd"))
         .EnableTokenAcquisitionToCallDownstreamApi()
         .AddInMemoryTokenCaches();

With the delegates:

  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
             .AddMicrosoftIdentityWebApp(microsoftIdentityOptions=>
             {
               Configuration.Bind("AzureAd", microsoftIdentityOptions);
               // do something
             })
            .EnableTokenAcquisitionToCallDownstreamApi(confidentialClientApplicationOptions=>
            {
              Configuration.Bind("AzureAd", confidentialClientApplicationOptions);
              // do something
             }
           )
          .AddInMemoryTokenCaches();

Note that when you use the override of AddMicrosoftIdentityWebApp with delegates, the only override of EnableTokenAcquisitionToCallDownstreamApi is the one with delegates (as the configuration is not known).

When you use the override of AddMicrosoftIdentityWebApp with configuration, you can use either the overrides of EnableTokenAcquisitionToCallDownstreamApi with configuration (which does not need to be passed again, as it's known from AddMicrosoftIdentityWebApp , or with delegates for the ConfidentialClientApplicationOptions.

web APIs

This is similar as for web apps

  services.AddMicrosoftIdentityWebApiAuthentication(Configuration)
              .EnableTokenAcquisitionToCallDownstreamApi()
              .AddInMemoryTokenCaches();

which is equivalent to:

            services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                AddMicrosoftIdentityWebApi(Configuration)
                .EnableTokenAcquisitionToCallDownstreamApi()
                .AddInMemoryTokenCaches();

which is really:

            services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, 
                                    jwtBearerScheme:JwtBearerDefaults.AuthenticationScheme,
                                    configSectionName:"AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi(initialScopes: null)
                .AddInMemoryTokenCaches();

Then with the delegates:

  services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
         .AddMicrosoftIdentityWebApi(
            options =>
            {
             Configuration.GetSection("AzureAd").Bind(options);
             // Do something
            },
            options =>
            {
             Configuration.GetSection("AzureAd").Bind(options);
            // Do something
           })
           .CallsWebApi(options => 
           {
            Configuration.GetSection("AzureAd").Bind(options);
            // do something
           } )
          .AddInMemoryTokenCaches();

which is really:

            services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(
                        options =>
                        {
                            Configuration.GetSection("AzureAd").Bind(options);
                            // Do something
                        },
                        options =>
                        {
                            Configuration.GetSection("AzureAd").Bind(options);
                            // Do something
                        },
                        jwtBearerScheme: JwtBearerDefaults.AuthenticationScheme,
                        subscribeToJwtBearerMiddlewareDiagnosticsEvents:false)
                .EnableTokenAcquisitionToCallDownstreamApi(options => Configuration.GetSection("AzureAd").Bind(options),
                initialScope=null)
                .AddInMemoryTokenCaches();

Note that EnableTokenAcquisitionToCallDownstreamApi really means: has the capability of calling a web API (acquiring tokens), that is making the ITokenAcquisition service available.

Calling Microsoft Graph and downstream APIs

From a web app, as from a web API, you can call either Microsoft Graph, or a downstream API.

 .EnableTokenAcquisitionToCallDownstreamApi
   .AddMicrosoftGraph()
   .AddDownstreamApi("MyApi", Configuration.GetSection("SectionForMyApi")
   .AddInMemoryTokenCaches();

Calling Microsoft Graph

AddMicrosoftGraph has three overrides:

.AddMicrosoftGraph(Configuration.GetSection("GraphBeta")

.AddMicrosoftGraph(options =>
  {
   options.BaseUrl = "https://graph.microsoft.com/beta";
   options.Scopes = "mail.read mail.write";
   });

.AddMicrosoftGraph(;

which uses the public cloud v1.0 Microsoft Graph API ("https://graph.microsoft.com/v1.0"), and "user.read" as scopes.

In the controllers/blazor pages /razor pages you can then inject GraphClientService and use it.

Calling Downstream APIs

AddDownstreamApi has two overrides:

  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
      .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
      .EnableTokenAcquisitionToCallDownstreamApi()
         .AddDownstreamWebApi("TodoList", Configuration.GetSection("TodoList"))
         .AddInMemoryTokenCaches();

and

   .AddDownstreamApi("MyApi", options =>
     {
       options.BaseUrl = "https://myapi.mydomain.com";
       options.Scopes = "api://guid/acces_as_user";
     });

It enables you, in the controllers/blazor pages/razor pages to then inject IDownstreamApi and use it to call the web API directly. See for instance: https://github.com/AzureAD/microsoft-identity-web/blob/fe145b3fbe75960faead1476176f7c63b8afd976/tests/WebAppCallsWebApiCallsGraph/Client/Controllers/TodoListController.cs#L22-L38

 public TodoListController(IDownstreamWebApi downstreamWebApi)
 {
  _downstreamWebApi = downstreamWebApi;
 }


 // GET: TodoList
 public async Task<ActionResult> Index()
 {
  var value = await _downstreamWebApi.CallWebApiForUserAsync<object, IEnumerable<Todo>>(
    ServiceName,
    null,
    options => { options.RelativePath = "api/todolist"; });

  return View(value);
 }

Samples

For a sample of a web app calling Microsoft Graph, see https://github.com/AzureAD/microsoft-identity-web/tree/master/tests/WebAppCallsMicrosoftGraph
For a sample of a web app calling a downstream API, see https://github.com/AzureAD/microsoft-identity-web/tree/master/tests/WebAppCallsWebApiCallsGraph

Other breaking changes

In Microsoft.Identity.Web.UI, AccountController.Challenge now has a new parameter (policy) to enable multi-policy.

AccountController : Controller 
{
        public IActionResult Challenge(string redirectUri, string scope, string loginHint, string domainHint, string claims, string policy);
}