Merge pull request #2 from mihirdilip/3.1.0

3.1.0

- Multitarget framework support added
- Source Link support added
- Strong Name Key support added
- SuppressWWWAuthenticateHeader added to configure options
- Events added to configure options

Author: mihirdilip

README.md

@@ -18,6 +18,8 @@ PM> Install-Package AspNetCore.Authentication.Basic
 
 ## Example Usage
 
+Samples are available under [samples directory](samples).
+
 Setting it up is quite simple. You will need basic working knowledge of ASP.NET Core 2.2 or newer to get started using this code.
 
 On [**Startup.cs**](#startupcs), as shown below, add 2 lines in *ConfigureServices* method `services.AddAuthentication(BasicDefaults.AuthenticationScheme).AddBasic<BasicUserValidationService>(options => { options.Realm = "My App"; });`. And a line `app.UseAuthentication();` in *Configure* method.
@@ -32,20 +34,20 @@ Also add an implementation of *IBasicUserValidationService* as shown below in [*
 using AspNetCore.Authentication.Basic;
 public class Startup
 {
-	public Startup(IConfiguration configuration)
-	{
-		Configuration = configuration;
-	}
-
-	public IConfiguration Configuration { get; }
-
 	public void ConfigureServices(IServiceCollection services)
 	{
 		// Add the Basic scheme authentication here..
-		// AddBasic extension takes an implementation of IBasicUserValidationService for validating the username and password. 
-		// It also requires Realm to be set in the options.
-		services.AddAuthentication(BasicDefaults.AuthenticationScheme)
-			.AddBasic<BasicUserValidationService>(options => { options.Realm = "My App"; });
+        // It requires Realm to be set in the options if SuppressWWWAuthenticateHeader is not set.
+        // If an implementation of IBasicUserValidationService interface is registered in the dependency register as well as OnValidateCredentials delegete on options.Events is also set then this delegate will be used instead of an implementation of IBasicUserValidationService.
+        services.AddAuthentication(BasicDefaults.AuthenticationScheme)
+
+            // The below AddBasic without type parameter will require OnValidateCredentials delegete on options.Events to be set unless an implementation of IBasicUserValidationService interface is registered in the dependency register.
+            // Please note if both the delgate and validation server are set then the delegate will be used instead of BasicUserValidationService.
+            //.AddBasic(options => { options.Realm = "My App"; });
+
+            // The below AddBasic with type parameter will add the BasicUserValidationService to the dependency register. 
+            // Please note if OnValidateCredentials delegete on options.Events is also set then this delegate will be used instead of BasicUserValidationService.
+            .AddBasic<BasicUserValidationService>(options => { options.Realm = "My App"; });
 
 		services.AddControllers();
 
@@ -81,20 +83,20 @@ public class Startup
 using AspNetCore.Authentication.Basic;
 public class Startup
 {
-	public Startup(IConfiguration configuration)
-	{
-		Configuration = configuration;
-	}
-
-	public IConfiguration Configuration { get; }
-
 	public void ConfigureServices(IServiceCollection services)
 	{
 		// Add the Basic scheme authentication here..
-		// AddBasic extension takes an implementation of IBasicUserValidationService for validating the username and password. 
-		// It also requires Realm to be set in the options.
-		services.AddAuthentication(BasicDefaults.AuthenticationScheme)
-			.AddBasic<BasicUserValidationService>(options => { options.Realm = "My App"; });
+        // It requires Realm to be set in the options if SuppressWWWAuthenticateHeader is not set.
+        // If an implementation of IBasicUserValidationService interface is registered in the dependency register as well as OnValidateCredentials delegete on options.Events is also set then this delegate will be used instead of an implementation of IBasicUserValidationService.
+        services.AddAuthentication(BasicDefaults.AuthenticationScheme)
+
+            // The below AddBasic without type parameter will require OnValidateCredentials delegete on options.Events to be set unless an implementation of IBasicUserValidationService interface is registered in the dependency register.
+            // Please note if both the delgate and validation server are set then the delegate will be used instead of BasicUserValidationService.
+            //.AddBasic(options => { options.Realm = "My App"; });
+
+            // The below AddBasic with type parameter will add the BasicUserValidationService to the dependency register. 
+            // Please note if OnValidateCredentials delegete on options.Events is also set then this delegate will be used instead of BasicUserValidationService.
+            .AddBasic<BasicUserValidationService>(options => { options.Realm = "My App"; });
 
 		services.AddMvc();
 
@@ -141,7 +143,44 @@ public class BasicUserValidationService : IBasicUserValidationService
 	}
 }
 ```
- 
+
+## Configuration (BasicOptions)
+#### Realm
+Required to be set if SuppressWWWAuthenticateHeader is not set to true. It is used with WWW-Authenticate response header when challenging un-authenticated requests.  
+   
+#### SuppressWWWAuthenticateHeader
+Default value is false.  
+When set to true, it will NOT return WWW-Authenticate response header when challenging un-authenticated requests.  
+When set to false, it will return WWW-Authenticate response header when challenging un-authenticated requests.
+
+#### Events
+The object provided by the application to process events raised by the basic authentication middleware.  
+The application may implement the interface fully, or it may create an instance of BasicEvents and assign delegates only to the events it wants to process.
+- ##### OnValidateCredentials
+	A delegate assigned to this property will be invoked just before validating credentials.  
+	You must provide a delegate for this property for authentication to occur.  
+	In your delegate you should either call context.ValidationSucceeded() which will handle construction of authentication principal from the user details which will be assiged the context.Principal property and call context.Success(), or construct an authentication principal from the user details & attach it to the context.Principal property and finally call context.Success() method.  
+	If only context.Principal property set without calling context.Success() method then, Success() method is automaticalled called.
+
+- ##### OnAuthenticationSucceeded  
+	A delegate assigned to this property will be invoked when the authentication succeeds. It will not be called if OnValidateCredentials delegate is assigned.  
+    It can be used for adding claims, headers, etc to the response.
+
+- ##### OnAuthenticationFailed  
+	A delegate assigned to this property will be invoked when the authentication fails.
+
+- ##### OnHandleChallenge  
+	A delegate assigned to this property will be invoked before a challenge is sent back to the caller when handling unauthorized response.  
+	Only use this if you know what you are doing and if you want to use custom implementation.  Set the delegate to deal with 401 challenge concerns, if an authentication scheme in question deals an authentication interaction as part of it's request flow. (like adding a response header, or changing the 401 result to 302 of a login page or external sign-in location.)  
+    Call context.Handled() at the end so that any default logic for this challenge will be skipped.
+
+- ##### OnHandleForbidden  
+	A delegate assigned to this property will be invoked if Authorization fails and results in a Forbidden response.  
+	Only use this if you know what you are doing and if you want to use custom implementation.  
+	Set the delegate to handle Forbid.  
+	Call context.Handled() at the end so that any default logic will be skipped.
+
+
 ## Additional Notes
 Please note that, by default, with ASP.NET Core, all the requests are not challenged for authentication. So don't worry if your *BasicUserValidationService* is not hit when you don't pass the required basic authentication details with the request. It is a normal behaviour. ASP.NET Core challenges authentication only when it is specifically told to do so either by decorating controller/method with *[Authorize]* filter attribute or by some other means. 
 
@@ -174,10 +213,9 @@ app.UseEndpoints(endpoints =>
 ``` 
 
 ## References
-- [Creating an authentication scheme in ASP.NET Core 2.0](https://joonasw.net/view/creating-auth-scheme-in-aspnet-core-2)
-- [aspnet/Security](https://github.com/aspnet/Security)
-- [ASP.NET Core Security documentation](https://docs.microsoft.com/en-us/aspnet/core/security)
 - [RFC 7617: Technical spec for HTTP Basic](https://tools.ietf.org/html/rfc7617)
+- [ASP.NET Core Security documentation](https://docs.microsoft.com/en-us/aspnet/core/security)
+- [aspnet/Security](https://github.com/dotnet/aspnetcore/tree/master/src/Security)
 
 ## License
-[MIT License](https://github.com/mihirdilip/aspnetcore-authentication-basic/blob/master/LICENSE.txt)
+[MIT License](https://github.com/mihirdilip/aspnetcore-authentication-basic/blob/master/LICENSE.txt)

samples/SampleWebApi/Controllers/ValuesController.cs

@@ -0,0 +1,34 @@
+using Microsoft.AspNetCore.Mvc;
+using System.Collections.Generic;
+using System.Text;
+
+namespace SampleWebApi_2_2.Controllers
+{
+    [Route("api/[controller]")]
+	public class ValuesController : ControllerBase
+	{
+		// GET api/values
+		[HttpGet]
+		public IEnumerable<string> Get()
+		{
+			return new string[] { "value1", "value2" };
+		}
+
+		[HttpGet("claims")]
+		public string Claims()
+        {
+			var sb = new StringBuilder();
+            foreach (var claim in User.Claims)
+            {
+				sb.AppendLine($"{claim.Type}: {claim.Value}");
+            }
+			return sb.ToString();
+        }
+
+		[HttpGet("forbid")]
+		public new IActionResult Forbid()
+		{
+			return base.Forbid();
+		}
+	}
+}

samples/SampleWebApi/Startup.cs

@@ -5,11 +5,14 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <Folder Include="wwwroot\" />
+    <Compile Remove="wwwroot\**" />
+    <Content Remove="wwwroot\**" />
+    <EmbeddedResource Remove="wwwroot\**" />
+    <None Remove="wwwroot\**" />
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="AspNetCore.Authentication.Basic" Version="2.2.0" />
+    <PackageReference Include="AspNetCore.Authentication.Basic" Version="3.1.0" />
     <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
   </ItemGroup>
 
@@ -18,5 +21,9 @@
   </ItemGroup>
 
   <Import Project="..\SampleWebApi.Shared\SampleWebApi.Shared.projitems" Label="Shared" />
+  
+  <!--<ItemGroup>
+    <ProjectReference Include="..\..\src\AspNetCore.Authentication.Basic\AspNetCore.Authentication.Basic.csproj" />
+  </ItemGroup>-->
 
 </Project>