Add a snippet that shows wo to use AuthorizationMiddlewareResultHandler (#20193)

* Add a snippet that shows wo to use AuthorizationMiddlewareResultHandler

* Bring over pravan AuthMiddlewareResultHander (#20198)

* Bring over pravan AuthMiddlewareResultHander

* clean up

* react to feedback

* react to feedback

* react to feedback

* react to feedback

* Apply suggestions from code review

Co-authored-by: Pranav K <prkrishn@hotmail.com>

* react to feedback

* react to feedback

* react to feedback

Co-authored-by: Pranav K <prkrishn@hotmail.com>

Co-authored-by: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com>

Author: pranavkm

aspnetcore/security/authorization/customizingauthorizationmiddlewareresponse.md

@@ -0,0 +1,24 @@
+---
+title: Customize the behavior of AuthorizationMiddleware
+author: pranavkm
+ms.author: prkrishn
+description: This article explains how to customize the result handling of AuthorizationMiddleware.
+monikerRange: '>= aspnetcore-5.0'
+uid: security/authorization/authorizationmiddlewareresulthandler
+---
+# Customize the behavior of AuthorizationMiddleware
+
+Applications can register a `Microsoft.AspNetCore.Authorization.IAuthorizationMiddlewareResultHandler` to customize the way the middleware handles the authorization results. Applications can use the customized middleware to:
+
+* Return customized responses.
+* Enhance the default challenge or forbid responses.
+
+The following code shows an example of an authorization handler that returns a custom response for certain kinds of authorization failures:
+
+[!code-csharp[](customizingauthorizationmiddlewareresponse/sample/AuthorizationMiddlewareResultHandlerSample/MyAuthorizationMiddlewareResultHandler.cs)]
+
+Register `MyAuthorizationMiddlewareResultHandler` in `Startup.ConfigureServices`:
+
+[!code-csharp[](customizingauthorizationmiddlewareresponse/sample/AuthorizationMiddlewareResultHandlerSample/Startup.cs?name=snippet)]
+
+<!-- <xref:Microsoft.AspNetCore.Authorization.IAuthorizationMiddlewareResultHandler /> -->

aspnetcore/security/authorization/customizingauthorizationmiddlewareresponse/sample/AuthorizationMiddlewareResultHandlerSample/MyAuthorizationMiddlewareResultHandler.cs

@@ -0,0 +1,41 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Authorization.Policy;
+using Microsoft.AspNetCore.Http;
+using System.Linq;
+using System.Net;
+using System.Threading.Tasks;
+
+public class MyAuthorizationMiddlewareResultHandler : IAuthorizationMiddlewareResultHandler
+{
+   private readonly AuthorizationMiddlewareResultHandler 
+        DefaultHandler = new AuthorizationMiddlewareResultHandler();
+	
+    public async Task HandleAsync(
+        RequestDelegate requestDelegate,
+        HttpContext httpContext,
+        AuthorizationPolicy authorizationPolicy,
+        PolicyAuthorizationResult policyAuthorizationResult)
+    {
+        // if the authorization was forbidden and the resource had specific requirements,
+        // provide a custom response.
+        if (Show404ForForbiddenResult(policyAuthorizationResult))
+        {
+            // Return a 404 to make it appear as if the resource does not exist.
+            httpContext.Response.StatusCode = (int)HttpStatusCode.NotFound;
+            return;
+        }
+
+        // Fallback to the default implementation.
+        await DefaultHandler.HandleAsync(requestDelegate, httpContext, authorizationPolicy, 
+                               policyAuthorizationResult);
+    }
+
+    bool Show404ForForbiddenResult(PolicyAuthorizationResult policyAuthorizationResult)
+    {
+        return policyAuthorizationResult.Forbidden &&
+            policyAuthorizationResult.AuthorizationFailure.FailedRequirements.OfType<
+                                                           Show404Requirement>().Any();
+    }
+}
+
+public class Show404Requirement : IAuthorizationRequirement { }

aspnetcore/security/authorization/customizingauthorizationmiddlewareresponse/sample/AuthorizationMiddlewareResultHandlerSample/Startup.cs

@@ -0,0 +1,60 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.HttpsPolicy;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+
+namespace AuthorizationMiddlewareResultHandlerSample
+{
+    public class Startup
+    {
+        public Startup(IConfiguration configuration)
+        {
+            Configuration = configuration;
+        }
+
+        public IConfiguration Configuration { get; }
+
+#region snippet
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddRazorPages();
+            services.AddSingleton<IAuthorizationMiddlewareResultHandler,
+                                  MyAuthorizationMiddlewareResultHandler>();
+        }
+        #endregion
+
+        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
+        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+        {
+            if (env.IsDevelopment())
+            {
+                app.UseDeveloperExceptionPage();
+            }
+            else
+            {
+                app.UseExceptionHandler("/Error");
+                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
+                app.UseHsts();
+            }
+
+            app.UseHttpsRedirection();
+            app.UseStaticFiles();
+
+            app.UseRouting();
+
+            app.UseAuthorization();
+
+            app.UseEndpoints(endpoints =>
+            {
+                endpoints.MapRazorPages();
+            });
+        }
+    }
+}

aspnetcore/toc.yml

@@ -1121,6 +1121,8 @@
           uid: security/authorization/policies
         - name: Authorization policy providers
           uid: security/authorization/iauthorizationpolicyprovider
+        - name: Customize the behavior of AuthorizationMiddleware
+          uid: security/authorization/authorizationmiddlewareresulthandler
         - name: Dependency injection in requirement handlers
           uid: security/authorization/dependencyinjection
         - name: Resource-based authorization