Addressing PR comments about overwriting custom OIDC and JWT events from the developer

Author: Tiago Brenck

Microsoft.Identity.Web/WebApiServiceCollectionExtensions.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.JwtBearer;
 using Microsoft.AspNetCore.Authentication.OpenIdConnect;
 using Microsoft.Extensions.Configuration;
@@ -59,20 +60,109 @@ public static IServiceCollection AddProtectedWebApi(
             bool subscribeToJwtBearerMiddlewareDiagnosticsEvents = false)
         {
             services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
-                    .AddJwtBearer((options => configuration.Bind(configSectionName, options)));
-                  
-            services.Configure<MicrosoftIdentityOptions>(options => configuration.Bind(configSectionName, options));
+                .AddProtectedWebApi(
+                    configSectionName,
+                    configuration,
+                    options => configuration.Bind(configSectionName, options),
+                    tokenDecryptionCertificate,
+                    subscribeToJwtBearerMiddlewareDiagnosticsEvents);
 
-            services.AddHttpContextAccessor();
+            return services;
+        }
+
+        /// <summary>
+        /// Protects the Web API with Microsoft identity platform (formerly Azure AD v2.0)
+        /// This method expects the configuration file will have a section, named "AzureAd" as default, with the necessary settings to initialize authentication options.
+        /// </summary>
+        /// <param name="builder">AuthenticationBuilder to which to add this configuration</param>
+        /// <param name="configuration">The Configuration object</param>
+        /// <param name="configureOptions">An action to configure JwtBearerOptions</param>
+        /// <param name="tokenDecryptionCertificate">Token decryption certificate</param>
+        /// <param name="subscribeToJwtBearerMiddlewareDiagnosticsEvents">
+        /// Set to true if you want to debug, or just understand the JwtBearer events.
+        /// </param>
+        /// <returns></returns>
+        public static AuthenticationBuilder AddProtectedWebApi(
+            this AuthenticationBuilder builder,
+            IConfiguration configuration,
+            Action<JwtBearerOptions> configureOptions,
+            X509Certificate2 tokenDecryptionCertificate = null,
+            bool subscribeToJwtBearerMiddlewareDiagnosticsEvents = false)
+        {
+            return AddProtectedWebApi(
+                builder,
+                "AzureAd",
+                configuration,
+                JwtBearerDefaults.AuthenticationScheme,
+                configureOptions,
+                tokenDecryptionCertificate,
+                subscribeToJwtBearerMiddlewareDiagnosticsEvents);
+        }
+
+        /// <summary>
+        /// Protects the Web API with Microsoft identity platform (formerly Azure AD v2.0)
+        /// This method expects the configuration file will have a section, named "AzureAd" as default, with the necessary settings to initialize authentication options.
+        /// </summary>
+        /// <param name="builder">AuthenticationBuilder to which to add this configuration</param>
+        /// <param name="configSectionName">The configuration section with the necessary settings to initialize authentication options</param>
+        /// <param name="configuration">The Configuration object</param>
+        /// <param name="configureOptions">An action to configure JwtBearerOptions</param>
+        /// <param name="tokenDecryptionCertificate">Token decryption certificate</param>
+        /// <param name="subscribeToJwtBearerMiddlewareDiagnosticsEvents">
+        /// Set to true if you want to debug, or just understand the JwtBearer events.
+        /// </param>
+        /// <returns></returns>
+        public static AuthenticationBuilder AddProtectedWebApi(
+            this AuthenticationBuilder builder,
+            string configSectionName,
+            IConfiguration configuration,
+            Action<JwtBearerOptions> configureOptions,
+            X509Certificate2 tokenDecryptionCertificate = null,
+            bool subscribeToJwtBearerMiddlewareDiagnosticsEvents = false)
+        {
+            return AddProtectedWebApi(
+                builder,
+                configSectionName,
+                configuration,
+                JwtBearerDefaults.AuthenticationScheme,
+                configureOptions,
+                tokenDecryptionCertificate,
+                subscribeToJwtBearerMiddlewareDiagnosticsEvents);
+        }
+
+        /// <summary>
+        /// Protects the Web API with Microsoft identity platform (formerly Azure AD v2.0)
+        /// This method expects the configuration file will have a section, named "AzureAd" as default, with the necessary settings to initialize authentication options.
+        /// </summary>
+        /// <param name="builder">AuthenticationBuilder to which to add this configuration</param>
+        /// <param name="configSectionName">The configuration section with the necessary settings to initialize authentication options</param>
+        /// <param name="configuration">The Configuration object</param>
+        /// <param name="jwtBearerScheme">The JwtBearer scheme name to be used. By default it uses "Bearer"</param>
+        /// <param name="configureOptions">An action to configure JwtBearerOptions</param>
+        /// <param name="tokenDecryptionCertificate">Token decryption certificate</param>
+        /// <param name="subscribeToJwtBearerMiddlewareDiagnosticsEvents">
+        /// Set to true if you want to debug, or just understand the JwtBearer events.
+        /// </param>
+        /// <returns></returns>
+        public static AuthenticationBuilder AddProtectedWebApi(
+            this AuthenticationBuilder builder,
+            string configSectionName,
+            IConfiguration configuration,
+            string jwtBearerScheme,
+            Action<JwtBearerOptions> configureOptions,
+            X509Certificate2 tokenDecryptionCertificate = null,
+            bool subscribeToJwtBearerMiddlewareDiagnosticsEvents = false)
+        {
+            builder.Services.Configure(jwtBearerScheme, configureOptions);
+            builder.Services.Configure<MicrosoftIdentityOptions>(options => configuration.Bind(configSectionName, options));
+
+            builder.Services.AddHttpContextAccessor();
 
             // Change the authentication configuration to accommodate the Microsoft identity platform endpoint (v2.0).
-            services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options =>
+            builder.AddJwtBearer(jwtBearerScheme, options =>
             {
                 var microsoftIdentityOptions = configuration.GetSection(configSectionName).Get<MicrosoftIdentityOptions>();
 
-                // Reinitialize the options as this has changed to JwtBearerOptions to pick configuration values for attributes unique to JwtBearerOptions
-                configuration.Bind(configSectionName, options);
-
                 if (string.IsNullOrWhiteSpace(options.Authority))
                     options.Authority = AuthorityHelpers.BuildAuthority(microsoftIdentityOptions);
 
@@ -82,48 +172,52 @@ public static IServiceCollection AddProtectedWebApi(
                 // The valid audiences are both the Client ID (options.Audience) and api://{ClientID}
                 options.TokenValidationParameters.ValidAudiences = new string[]
                 {
-                    // If the developer doesnt set the Audience on JwtBearerOptions, use ClientId from MicrosoftIdentityOptions
+                    // If the developer doesn't set the Audience on JwtBearerOptions, use ClientId from MicrosoftIdentityOptions
                     options.Audience, $"api://{options.Audience ?? microsoftIdentityOptions.ClientId}"
                 };
 
-                // Instead of using the default validation (validating against a single tenant, as we do in line of business apps),
-                // we inject our own multi-tenant validation logic (which even accepts both v1.0 and v2.0 tokens)
-                options.TokenValidationParameters.IssuerValidator = AadIssuerValidator.GetIssuerValidator(options.Authority).Validate;
+                // If the developer registered an IssuerValidator, do not overwrite it
+                if (options.TokenValidationParameters.IssuerValidator == null)
+                {
+                    // Instead of using the default validation (validating against a single tenant, as we do in line of business apps),
+                    // we inject our own multi-tenant validation logic (which even accepts both v1.0 and v2.0 tokens)
+                    options.TokenValidationParameters.IssuerValidator = AadIssuerValidator.GetIssuerValidator(options.Authority).Validate;
+                }
 
                 // If you provide a token decryption certificate, it will be used to decrypt the token
                 if (tokenDecryptionCertificate != null)
                 {
                     options.TokenValidationParameters.TokenDecryptionKey = new X509SecurityKey(tokenDecryptionCertificate);
                 }
 
+                if (options.Events == null)
+                    options.Events = new JwtBearerEvents();
+
                 // When an access token for our own Web API is validated, we add it to MSAL.NET's cache so that it can
                 // be used from the controllers.
-                options.Events = new JwtBearerEvents();
-
+                var tokenValidatedHandler = options.Events.OnTokenValidated;
                 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);
-                   };
+                {
+                    // 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 tokenValidatedHandler(context).ConfigureAwait(false);
+                };
 
                 if (subscribeToJwtBearerMiddlewareDiagnosticsEvents)
                 {
                     options.Events = JwtBearerMiddlewareDiagnostics.Subscribe(options.Events);
                 }
             });
 
-            return services;
+            return builder;
         }
 
-        // TODO: pass an option with a section name to bind the options ? or a delegate?
-
         /// <summary>
         /// Protects the Web API with Microsoft identity platform (formerly Azure AD v2.0)
         /// This supposes that the configuration files have a section named configSectionName (typically "AzureAD")
@@ -141,8 +235,7 @@ public static IServiceCollection AddProtectedWebApiCallsProtectedWebApi(
             services.AddHttpContextAccessor();
             services.Configure<ConfidentialClientApplicationOptions>(options => configuration.Bind(configSectionName, options));
             services.Configure<MicrosoftIdentityOptions>(options => configuration.Bind(configSectionName, options));
-            
-            // TODO: Pass scheme as parameter?
+
             services.Configure<JwtBearerOptions>(jwtBearerScheme, options =>
             {
                 options.Events.OnTokenValidated = async context =>

Microsoft.Identity.Web/WebAppServiceCollectionExtensions.cs

@@ -94,20 +94,22 @@ public static IServiceCollection AddWebAppCallsProtectedWebApi(
 
                 // Handling the auth redemption by MSAL.NET so that a token is available in the token cache
                 // where it will be usable from Controllers later (through the TokenAcquisition service)
-                var handler = options.Events.OnAuthorizationCodeReceived;
+                var codeReceivedHandler = options.Events.OnAuthorizationCodeReceived;
                 options.Events.OnAuthorizationCodeReceived = async context =>
                 {
                     var tokenAcquisition = context.HttpContext.RequestServices.GetRequiredService<ITokenAcquisition>();
                     await tokenAcquisition.AddAccountToCacheFromAuthorizationCodeAsync(context, options.Scope).ConfigureAwait(false);
-                    await handler(context).ConfigureAwait(false);
+                    await codeReceivedHandler(context).ConfigureAwait(false);
                 };
 
                 // Handling the sign-out: removing the account from MSAL.NET cache
+                var signOutHandler = options.Events.OnRedirectToIdentityProviderForSignOut;
                 options.Events.OnRedirectToIdentityProviderForSignOut = async context =>
                 {
                     // Remove the account from MSAL.NET token cache
                     var tokenAcquisition = context.HttpContext.RequestServices.GetRequiredService<ITokenAcquisition>();
                     await tokenAcquisition.RemoveAccountAsync(context).ConfigureAwait(false);
+                    await signOutHandler(context).ConfigureAwait(false);
                 };
             });
             return services;
@@ -205,6 +207,7 @@ public static AuthenticationBuilder AddSignIn(
 
                 options.TokenValidationParameters.NameClaimType = "preferred_username";
 
+                // If the developer registered an IssuerValidator, do not overwrite it
                 if (options.TokenValidationParameters.IssuerValidator == null)
                 {
                     // If you want to restrict the users that can sign-in to several organizations
@@ -215,7 +218,8 @@ public static AuthenticationBuilder AddSignIn(
 
                 // Avoids having users being presented the select account dialog when they are already signed-in
                 // for instance when going through incremental consent
-                options.Events.OnRedirectToIdentityProvider = context =>
+                var redirectToIdpHandler = options.Events.OnRedirectToIdentityProvider;
+                options.Events.OnRedirectToIdentityProvider = async context =>
                 {
                     var login = context.Properties.GetParameter<string>(OpenIdConnectParameterNames.LoginHint);
                     if (!string.IsNullOrWhiteSpace(login))
@@ -242,18 +246,24 @@ public static AuthenticationBuilder AddSignIn(
                     {
                         // When a new Challenge is returned using any B2C policy different than sisu, we must change
                         // the ProtocolMessage.IssuerAddress to the desired policy otherwise the redirect would use the sisu policy
-                        b2COidcHandlers.OnRedirectToIdentityProvider(context);
+                        await b2COidcHandlers.OnRedirectToIdentityProvider(context);
                     }
 
-                    return Task.FromResult(0);
+                    await redirectToIdpHandler(context).ConfigureAwait(false);
                 };
 
                 if (microsoftIdentityOptions.IsB2C)
                 {
-                    // Handles the error when a user cancels an action on the Azure Active Directory B2C UI.
-                    // Handle the error code that Azure Active Directory B2C throws when trying to reset a password from the login page 
-                    // because password reset is not supported by a "sign-up or sign-in policy".
-                    options.Events.OnRemoteFailure = b2COidcHandlers.OnRemoteFailure;
+                    var remoteFailureHandler = options.Events.OnRemoteFailure;
+                    options.Events.OnRemoteFailure = async context =>
+                    {
+                        // Handles the error when a user cancels an action on the Azure Active Directory B2C UI.
+                        // Handle the error code that Azure Active Directory B2C throws when trying to reset a password from the login page 
+                        // because password reset is not supported by a "sign-up or sign-in policy".
+                        await b2COidcHandlers.OnRemoteFailure(context);
+
+                        await remoteFailureHandler(context).ConfigureAwait(false);
+                    };
                 }
 
                 if (subscribeToOpenIdConnectMiddlewareDiagnosticsEvents)