Update client IP address safelist doc and app for ASP.NET Core 3.1 (#17281)

* Update client IP address safelist doc and sample app for ASP.NET Core 3.1

* Add solution files

* Remove unused region

* Replace HTTP 401 with 403

* Add class-level regions for filters

* More work

* More tweaks

* More edits

* More work

* Sample app refactoring

* minor edit

* Fix code snippet include

* more edits

* Remove 4 moniker ranges

* Display doc for 2.1+ only

* Remove 2 more moniker ranges

Author: scottaddie

aspnetcore/security/ip-safelist.md

@@ -1,70 +1,119 @@
 ---
 title: Client IP safelist for ASP.NET Core
 author: damienbod
-description: Learn how to write Middleware or action filters to validate remote IP addresses against a list of approved IP addresses.
+description: Learn how to write middleware or action filters to validate remote IP addresses against a list of approved IP addresses.
+monikerRange: '>= aspnetcore-2.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 08/31/2018
+ms.date: 03/12/2020
 uid: security/ip-safelist
 ---
 # Client IP safelist for ASP.NET Core
 
 By [Damien Bowden](https://twitter.com/damien_bod) and [Tom Dykstra](https://github.com/tdykstra)
 
-This article shows three ways to implement an IP safelist (also known as a whitelist) in an ASP.NET Core app. You can use:
+This article shows three ways to implement an IP address safelist (also known as an allow list) in an ASP.NET Core app. An accompanying sample app demonstrates all three approaches. You can use:
 
 * Middleware to check the remote IP address of every request.
-* Action filters to check the remote IP address of requests for specific controllers or action methods.
+* MVC action filters to check the remote IP address of requests for specific controllers or action methods.
 * Razor Pages filters to check the remote IP address of requests for Razor pages.
 
-In each case, a string containing approved client IP addresses is stored in an app setting. The middleware or filter parses the string into a list and checks if the remote IP is in the list. If not, an HTTP 403 Forbidden status code is returned.
+In each case, a string containing approved client IP addresses is stored in an app setting. The middleware or filter:
 
-[View or download sample code](https://github.com/dotnet/AspNetCore.Docs/tree/master/aspnetcore/security/ip-safelist/samples/2.x/ClientIpAspNetCore) ([how to download](xref:index#how-to-download-a-sample))
+* Parses the string into an array. 
+* Checks if the remote IP address exists in the array.
 
-## The safelist
+Access is allowed if the array contains the IP address. Otherwise, an HTTP 403 Forbidden status code is returned.
 
-The list is configured in the *appsettings.json* file. It's a semicolon-delimited list and can contain IPv4 and IPv6 addresses.
+[View or download sample code](https://github.com/dotnet/AspNetCore.Docs/tree/master/aspnetcore/security/ip-safelist/samples) ([how to download](xref:index#how-to-download-a-sample))
 
-[!code-json[](ip-safelist/samples/2.x/ClientIpAspNetCore/appsettings.json?highlight=2)]
+## IP address safelist
+
+In the sample app, the IP address safelist is:
+
+* Defined by the `AdminSafeList` property in the *appsettings.json* file.
+* A semicolon-delimited string that may contain both [Internet Protocol version 4 (IPv4)](https://wikipedia.org/wiki/IPv4) and [Internet Protocol version 6 (IPv6)](https://wikipedia.org/wiki/IPv6) addresses.
+
+[!code-json[](ip-safelist/samples/3.x/ClientIpAspNetCore/appsettings.json?range=1-3&highlight=2)]
+
+In the preceding example, the IPv4 addresses of `127.0.0.1` and `192.168.1.5` and the IPv6 loopback address of `::1` (compressed format for `0:0:0:0:0:0:0:1`) are allowed.
 
 ## Middleware
 
-The `Configure` method adds the middleware and passes the safelist string to it in a constructor parameter.
+The `Startup.Configure` method adds the custom `AdminSafeListMiddleware` middleware type to the app's request pipeline. The safelist is retrieved with the .NET Core configuration provider and is passed as a constructor parameter.
 
-[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Startup.cs?name=snippet_Configure&highlight=10)]
+[!code-csharp[](ip-safelist/samples/3.x/ClientIpAspNetCore/Startup.cs?name=snippet_ConfigureAddMiddleware)]
 
-The middleware parses the string into an array and looks for the remote IP address in the array. If the remote IP address is not found, the middleware returns HTTP 401 Forbidden. This validation process is bypassed for HTTP Get requests.
+The middleware parses the string into an array and searches for the remote IP address in the array. If the remote IP address isn't found, the middleware returns HTTP 403 Forbidden. This validation process is bypassed for HTTP GET requests.
 
-[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/AdminSafeListMiddleware.cs?name=snippet_ClassOnly)]
+[!code-csharp[](ip-safelist/samples/Shared/ClientIpSafelistComponents/Middlewares/AdminSafeListMiddleware.cs?name=snippet_ClassOnly)]
 
 ## Action filter
 
-If you want a safelist only for specific controllers or action methods, use an action filter. Here's an example: 
+If you want safelist-driven access control for specific MVC controllers or action methods, use an action filter. For example:
+
+[!code-csharp[](ip-safelist/samples/Shared/ClientIpSafelistComponents/Filters/ClientIpCheckActionFilter.cs?name=snippet_ClassOnly)]
+
+In `Startup.ConfigureServices`, add the action filter to the MVC filters collection. In the following example, a `ClientIpCheckActionFilter` action filter is added. A safelist and a console logger instance are passed as constructor parameters.
+
+::: moniker range=">= aspnetcore-3.0"
+
+[!code-csharp[](ip-safelist/samples/3.x/ClientIpAspNetCore/Startup.cs?name=snippet_ConfigureServicesActionFilter)]
+
+::: moniker-end
+
+::: moniker range="<= aspnetcore-2.2"
+
+[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Startup.cs?name=snippet_ConfigureServicesActionFilter)]
+
+::: moniker-end
+
+The action filter can then be applied to a controller or action method with the [[ServiceFilter]](xref:Microsoft.AspNetCore.Mvc.ServiceFilterAttribute) attribute:
+
+[!code-csharp[](ip-safelist/samples/3.x/ClientIpAspNetCore/Controllers/ValuesController.cs?name=snippet_ActionFilter&highlight=1)]
+
+In the sample app, the action filter is applied to the controller's `Get` action method. When you test the app by sending:
+
+* An HTTP GET request, the `[ServiceFilter]` attribute validates the client IP address. If access is allowed to the `Get` action method, a variation of the following console output is produced by the action filter and action method:
+
+    ```
+    dbug: ClientIpSafelistComponents.Filters.ClientIpCheckActionFilter[0]
+          Remote IpAddress: ::1
+    dbug: ClientIpAspNetCore.Controllers.ValuesController[0]
+          successful HTTP GET    
+    ```
+
+* An HTTP request verb other than GET, the `AdminSafeListMiddleware` middleware validates the client IP address.
 
-[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Filters/ClientIpCheckFilter.cs)]
+## Razor Pages filter
 
-The action filter is added to the services container.
+If you want safelist-driven access control for a Razor Pages app, use a Razor Pages filter. For example:
 
-[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Startup.cs?name=snippet_ConfigureServices&highlight=3)]
+[!code-csharp[](ip-safelist/samples/Shared/ClientIpSafelistComponents/Filters/ClientIpCheckPageFilter.cs?name=snippet_ClassOnly)]
 
-The filter can then be used on a controller or action method.
+In `Startup.ConfigureServices`, enable the Razor Pages filter by adding it to the MVC filters collection. In the following example, a `ClientIpCheckPageFilter` Razor Pages filter is added. A safelist and a console logger instance are passed as constructor parameters.
 
-[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Controllers/ValuesController.cs?name=snippet_Filter&highlight=1)]
+::: moniker range=">= aspnetcore-3.0"
 
-In the sample app, the filter is applied to the `Get` method. So when you test the app by sending a `Get` API request, the attribute is validating the client IP address. When you test by calling the API with any other HTTP method, the middleware is validating the client IP.
+[!code-csharp[](ip-safelist/samples/3.x/ClientIpAspNetCore/Startup.cs?name=snippet_ConfigureServicesPageFilter)]
 
-## Razor Pages filter 
+::: moniker-end
 
-If you want a safelist for a Razor Pages app, use a Razor Pages filter. Here's an example: 
+::: moniker range="<= aspnetcore-2.2"
 
-[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Filters/ClientIpCheckPageFilter.cs)]
+[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Startup.cs?name=snippet_ConfigureServicesPageFilter)]
 
-This filter is enabled by adding it to the MVC Filters collection.
+::: moniker-end
 
-[!code-csharp[](ip-safelist/samples/2.x/ClientIpAspNetCore/Startup.cs?name=snippet_ConfigureServices&highlight=7-9)]
+When the sample app's *Index* Razor page is requested, the Razor Pages filter validates the client IP address. The filter produces a variation of the following console output:
 
-When you run the app and request a Razor page, the Razor Pages filter is validating the client IP.
+```
+dbug: ClientIpSafelistComponents.Filters.ClientIpCheckPageFilter[0]
+      Remote IpAddress: ::1
+```
 
-## Next steps
+## Additional resources
 
-[Learn more about ASP.NET Core Middleware](xref:fundamentals/middleware/index).
+* <xref:fundamentals/middleware/index>
+* [Action filters](xref:mvc/controllers/filters#action-filters)
+* <xref:razor-pages/filter>

aspnetcore/security/ip-safelist/samples/2.x/AspNetCore2.x.sln

@@ -0,0 +1,31 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 16
+VisualStudioVersion = 16.0.29806.167
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ClientIpAspNetCore", "ClientIpAspNetCore\ClientIpAspNetCore.csproj", "{51B901C7-2081-4CC2-A970-1C48A33E5507}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ClientIpSafelistComponents", "..\Shared\ClientIpSafelistComponents\ClientIpSafelistComponents.csproj", "{419CE413-A0F4-4415-B93E-F2D95B272921}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{51B901C7-2081-4CC2-A970-1C48A33E5507}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{51B901C7-2081-4CC2-A970-1C48A33E5507}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{51B901C7-2081-4CC2-A970-1C48A33E5507}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{51B901C7-2081-4CC2-A970-1C48A33E5507}.Release|Any CPU.Build.0 = Release|Any CPU
+		{419CE413-A0F4-4415-B93E-F2D95B272921}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{419CE413-A0F4-4415-B93E-F2D95B272921}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{419CE413-A0F4-4415-B93E-F2D95B272921}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{419CE413-A0F4-4415-B93E-F2D95B272921}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {DE6B1697-AE16-4BE0-ACF1-F31CD304CCCF}
+	EndGlobalSection
+EndGlobal

aspnetcore/security/ip-safelist/samples/2.x/ClientIpAspNetCore/ClientIpAspNetCore.csproj

@@ -2,22 +2,15 @@
 
   <PropertyGroup>
     <TargetFramework>netcoreapp2.1</TargetFramework>
+    <ProjectUISubcaption>ASP.NET Core 2.x</ProjectUISubcaption>
   </PropertyGroup>
 
   <ItemGroup>
     <PackageReference Include="Microsoft.AspNetCore.App" />
-    <PackageReference Include="NLog.Extensions.Logging" Version="1.2.1" />
-    <PackageReference Include="NLog.Web.AspNetCore" Version="4.6.0" />
-    <PackageReference Include="NLog" Version="4.5.9" />
   </ItemGroup>
 
   <ItemGroup>
-    <Content Update="nlog.config">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </Content>
-    <Content Update="nlog.file.config">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </Content>
+    <ProjectReference Include="..\..\Shared\ClientIpSafelistComponents\ClientIpSafelistComponents.csproj" />
   </ItemGroup>
 
 </Project>

aspnetcore/security/ip-safelist/samples/2.x/ClientIpAspNetCore/Controllers/ValuesController.cs

@@ -1,53 +1,40 @@
-using System.Collections.Generic;
-using ClientIpAspNetCore.Filters;
+using ClientIpSafelistComponents.Filters;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
+using System.Collections.Generic;
 
 namespace ClientIpAspNetCore.Controllers
 {
-    [Route("api/[controller]")]
-    public class ValuesController : Controller
+    [ApiController]
+    [Route("[controller]")]
+    public class ValuesController : ControllerBase
     {
-        private ILogger<ValuesController> _logger;
+        private readonly ILogger<ValuesController> _logger;
 
         public ValuesController(ILogger<ValuesController> logger)
         {
             _logger = logger;
         }
 
-        // GET api/values
-        #region snippet_Filter
-        [ServiceFilter(typeof(ClientIpCheckFilter))]
+        #region snippet_ActionFilter
+        [ServiceFilter(typeof(ClientIpCheckActionFilter))]
         [HttpGet]
         public IEnumerable<string> Get()
-        #endregion
+        #endregion snippet_ActionFilter
         {
-            _logger.LogDebug("successful get.");
+            _logger.LogDebug("successful HTTP GET");
+
             return new string[] { "value1", "value2" };
         }
 
-        // GET api/values/5
         [HttpGet("{id}")]
         public string Get(int id)
         {
             return "value";
         }
 
-        // POST api/values
         [HttpPost]
-        public void Post([FromBody]string value)
-        {
-        }
-
-        // PUT api/values/5
-        [HttpPut("{id}")]
-        public void Put(int id, [FromBody]string value)
-        {
-        }
-
-        // DELETE api/values/5
-        [HttpDelete("{id}")]
-        public void Delete(int id)
+        public void Post(string value)
         {
         }
     }

aspnetcore/security/ip-safelist/samples/2.x/ClientIpAspNetCore/Pages/Index.cshtml

@@ -1,7 +1,7 @@
 @page
-@model IndexModel
+@model ClientIpAspNetCore.Pages.IndexModel
 @{
-    ViewData["Title"] = "ClientIpAspNetCore page";
+    ViewData["Title"] = "Index";
 }
 
 Empty Page to use Filter

aspnetcore/security/ip-safelist/samples/2.x/ClientIpAspNetCore/Pages/Index.cshtml.cs

@@ -1,9 +1,4 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Threading.Tasks;
-using Microsoft.AspNetCore.Mvc;
-using Microsoft.AspNetCore.Mvc.RazorPages;
+using Microsoft.AspNetCore.Mvc.RazorPages;
 
 namespace ClientIpAspNetCore.Pages
 {

aspnetcore/security/ip-safelist/samples/2.x/ClientIpAspNetCore/Pages/Shared/_Layout.cshtml

@@ -1,7 +1,5 @@
 using Microsoft.AspNetCore;
 using Microsoft.AspNetCore.Hosting;
-using System;
-using NLog.Web;
 using Microsoft.Extensions.Logging;
 
 namespace ClientIpAspNetCore
@@ -10,34 +8,17 @@ public class Program
     {
         public static void Main(string[] args)
         {
-            var logger = NLog.Web.NLogBuilder.ConfigureNLog("nlog.config").GetCurrentClassLogger();
-            try
-            {
-                logger.Debug("init main");
-                BuildWebHost(args).Run();
-            }
-            catch (Exception ex)
-            {
-                //NLog: catch setup errors
-                logger.Error(ex, "Stopped program because of exception");
-                throw;
-            }
-            finally
-            {
-                // Ensure to flush and stop internal timers/threads before application-exit (Avoid segmentation fault on Linux)
-                NLog.LogManager.Shutdown();
-            }
+            BuildWebHost(args).Run();
         }
 
         public static IWebHost BuildWebHost(string[] args) =>
-                WebHost.CreateDefaultBuilder(args)
-                    .UseStartup<Startup>()
-                    .ConfigureLogging(logging =>
-                    {
-                        logging.ClearProviders();
-                        logging.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Trace);
-                    })
-                    .UseNLog()  // NLog: setup NLog for Dependency injection
-                    .Build();
+            WebHost.CreateDefaultBuilder(args)
+                .UseStartup<Startup>()
+                .ConfigureLogging(logging =>
+                {
+                    logging.ClearProviders();
+                    logging.AddConsole();
+                })
+                .Build();
     }
 }