Customization

Customization in Configuration

The "AzureAd" (or "AzureADB2C") section of the appsettings.json is mapped to several classes:

• MicrosoftIdentityOptions
• ConfidentialClientApplicationOptions

You can therefore use any of these settings in appsettings.json.

Customization in the Startup.cs

If you want to customize options, like OpenIdConnectOptions or JwtBearerOptions, but still want to benefit from the implementation provided by Microsoft Identity Web; you can do so by using Configure and PostConfigure methods in Startup.cs.

Let's take, for example, the AddMicrosoftIdentityWebApi or AddMicrosoftIdentityWebApiAuthentication methods (used to be AddProtectedWebApi in Microsoft Identity Web 0.1.x). In it, you'll see this event set up:

options.Events.OnTokenValidated = async context =>
{
    // This check is required to ensure that the web API only accepts tokens from tenants where it has been consented and provisioned.
    if (!context.Principal.Claims.Any(x => x.Type == ClaimConstants.Scope)
    && !context.Principal.Claims.Any(y => y.Type == ClaimConstants.Scp)
    && !context.Principal.Claims.Any(y => y.Type == ClaimConstants.Roles))
    {
         throw new UnauthorizedAccessException("Neither scope or roles claim was found in the bearer token.");
    }

    await Task.FromResult(0);
};

Say you want to augment the current ClaimsPrincipal by adding claims to it, and you have to do it on OnTokenValidated. However, you don't want to lose the UnauthorizedAccessException check existing in the event. To do so, in your Startup.cs, you'd have:

services.AddMicrosoftIdentityWebApiAuthentication(Configuration);
services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options =>
{
  var existingOnTokenValidatedHandler = options.Events.OnTokenValidated ;
  options.Events.OnTokenValidated = async context =>
  {
       await existingOnTokenValidatedHandler(context);
      // Your code to add extra claims that will be executed after the current event implementation.
  }
});

Other types of options can be customized in similar fashion:

Cookie related options

services.Configure<CookiePolicyOptions>(options =>
{
    // Custom code here.
});

services.Configure<CookieAuthenticationOptions>(CookieAuthenticationDefaults.AuthenticationScheme, options =>
{
    // Custom code here.
});

OpenIdConnectOptions

services.Configure<OpenIdConnectOptions>(OpenIdConnectDefaults.AuthenticationScheme, options =>
{
    // Custom code here.
});

If you want to override the default response_type of code, you can override it. In the code, for example:

services.Configure<OpenIdConnectOptions>(OpenIdConnectDefaults.AuthenticationScheme, options =>
{
   options.ResponseType = "code id_token";
});

For example to add extra query parameters to the URL sent to Azure AD:

services.Configure<OpenIdConnectOptions>(OpenIdConnectDefaults.AuthenticationScheme, options =>
{
 var previous = options.Events.OnRedirectToIdentityProvider;
 options.Events.OnRedirectToIdentityProvider = async context =>
 {
  if (previous != null)
  {
   await previous(context);
  }
  context.ProtocolMessage.Parameters.Add("slice", "testslice");
 };
});

How to query Microsoft Graph on token validated

// Sign-in users with the Microsoft identity platform
services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
        .AddMicrosoftIdentityWebApp(
           options =>
           {
            Configuration.Bind("AzureAd", options);
            options.Events = new OpenIdConnectEvents();
            var previousOnTokenValidatedHandler = options.Events.OnTokenValidated;
            options.Events.OnTokenValidated = async context =>
            {
             // Let Microsoft.Identity.Web process the token
             await previousOnTokenValidatedHandler(context).ConfigureAwait(false);

             // Calls method to process groups overage claim.
             var overageGroupClaims = await GraphHelper.GetSignedInUsersGroups(context);             
            };
           })
           .EnableTokenAcquisitionToCallDownstreamApi(options => Configuration.Bind("AzureAd", options), initialScopes)
             .AddMicrosoftGraph(Configuration.GetSection("GraphAPI"))
             .AddInMemoryTokenCaches();

For more details, see the active-directory-aspnetcore-webapp-openidconnect-v2 sample in chapter 5-2-Groups/Startup.cs#L41-L56.

MicrosoftIdentityOptions

services.Configure<MicrosoftIdentityOptions>(options =>
{
    // Custom code here.
});

When configuring options, verify that the correct authentication scheme is passed in, or none at all. Additionally, the middleware configuration methods are invoked in the order in which they were called, with PostConfigure methods executing after all the Configure methods.

Customizations to acquire tokens

Using the ITokenAcquisition interface

You have, from Microsoft.Identity.Web 1.0.0, the possibilty of passing tokenAcquisitionOptions to the ITokenAcquisition.GetAccessTokenForUserAsync() and .GetAccessTokenForAppAsync() methods in order to specify a CorrelationId, or extra query parameters.

 public async Task<IEnumerable<Todo>> GetAsync()
 {
  TokenAcquisitionOptions tokenAcquisitionOptions = new TokenAcquisitionOptions()
  {
   CorrelationId = correlationIdYouHaveReceived,
   ExtraQueryParameters = new Dictionary<string, string> 
     { { "slide", "test_slice" } }
  };

  string token = await _tokenAcquisition.GetAccessTokenForUserAsync(new string[] { "user.read" },
                tokenAcquisitionOptions: tokenAcquisitionOptions)
            .ConfigureAwait(false);
  // Do something with the token
 }

Using the IDownstream API interface

If you are using the IDownstreamApi interface, you'll have the same capability in the TokenAcquisitionOptions member of the DownstreamApiOptions passed to the delegate that enable you to configure the web API to call:

public async Task<ActionResult> Details(int id)
{
 var value = await _downstreamWebApi.CallWebApiForUserAsync<object, Todo>(
    ServiceName,
    null,
    options =>
    {
     options.HttpMethod = HttpMethod.Get;
     options.RelativePath = $"api/todolist/{id}";
     options.TokenAcquisitionOptions.CorrelationId = correlationId;
     options.TokenAcquisitionOptions.ExtraQueryParameters = 
       new Dictionary<string, string> { { "slide", "test_slice" } };
    });
 return View(value);
}

UI Customization

Redirect to a particular page after sign-in

After sign-in you can redirect to a particular page by precising the redirectUri parameter of the /MicrosoftIdentity/Account/SignIn action:

<a href="/MicrosoftIdentity/Account/SignIn?redirectUri=/TodoList">Sign In</a>

Implement a custom SignedOut page

The Microsoft Identity Web UI is implemented with MVC, which can cause issues for developers using Blazor, especially with navigation components. Adding a Areas/MicrosoftIdentity/Pages/Account/SignedOut.cshtml file will enable you to override the default /MicrosoftIdentity/Account/SignedOut page.

Also, to override the markup of the SignedOut.html page, the page can be overridden, as shown here.

See also the discussions in issue #758