Merge pull request #8 from jabbera/updatePullReq

Update RutaModule

Author: jabbera

RutaHttpModule.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 15
-VisualStudioVersion = 15.0.25914.0
+VisualStudioVersion = 15.0.26020.0
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RutaHttpModule", "RutaHttpModule\RutaHttpModule.csproj", "{F582ADD6-A40A-45F2-A046-ABC48A350B16}"
 EndProject
@@ -15,6 +15,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{0BCA4263-3544-4706-BFCB-664DEACB36EC}"
 	ProjectSection(SolutionItems) = preProject
 		ConfigureServer.ps1 = ConfigureServer.ps1
+		README.md = README.md
 		web-scanner.config = web-scanner.config
 		web-user.config = web-user.config
 	EndProjectSection

RutaHttpModule/ITraceSource.cs

@@ -0,0 +1,19 @@
+namespace RutaHttpModule
+{
+    using System.Diagnostics;
+
+    /// <summary>
+    /// Interface for implementations sending trace messages.
+    /// </summary>
+    internal interface ITraceSource
+    {
+        /// <summary>
+        /// Writes a trace event message to the trace listeners using the specified event type, 
+        /// event identifier, and message.
+        /// </summary>
+        /// <param name="eventType">One of the enumeration values that specifies the event type of the trace data.</param>
+        /// <param name="id">An event identifier.</param>
+        /// <param name="message">The trace message to write.</param>
+        void TraceEvent(TraceEventType eventType, int id, string message);
+    }
+}

RutaHttpModule/RutaHttpModule.csproj

@@ -56,6 +56,7 @@
     <Compile Include="IAdInteraction.cs" />
     <Compile Include="IRutaHttpContext.cs" />
     <Compile Include="ISettings.cs" />
+    <Compile Include="ITraceSource.cs" />
     <Compile Include="LdapExtensions.cs" />
     <Compile Include="Properties\Settings.Designer.cs">
       <AutoGen>True</AutoGen>
@@ -65,6 +66,7 @@
     <Compile Include="RutaHttpContext.cs" />
     <Compile Include="RutaModule.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
+    <Compile Include="RutaTraceSource.cs" />
     <Compile Include="SettingsWrapper.cs" />
   </ItemGroup>
   <ItemGroup>

RutaHttpModule/RutaModule.cs

@@ -1,125 +1,198 @@
-using System;
-using System.Diagnostics;
-using System.Diagnostics.CodeAnalysis;
-using System.Linq;
-using System.Web;
-
-namespace RutaHttpModule
+namespace RutaHttpModule
 {
+    using System;
+    using System.Diagnostics;
+    using System.Diagnostics.CodeAnalysis;
+    using System.Linq;
+    using System.Web;
+
+    /// <summary>
+    /// This module changes adds all header information needed for interaction with SonarQube and 
+    /// provide a SSO experience. An existing Authorization header will be removed.
+    /// </summary>
+    /// <remarks>
+    /// See also https://www.iis.net/learn/develop/runtime-extensibility/how-to-add-tracing-to-iis-managed-modules
+    /// </remarks>
     public sealed class RutaModule : IHttpModule
     {
+        /// <summary>
+        /// Reference to the implementation needed to query the AD.
+        /// </summary>
         private readonly IAdInteraction adInteraction;
+
+        /// <summary>
+        /// Reference to the settings needed for constructing the right header.
+        /// </summary>
         private readonly ISettings settings;
-        private TraceSource traceSource;
 
+        /// <summary>
+        /// Reference to the tracing object.
+        /// </summary>
+        private ITraceSource traceSource;
+
+        /// <summary>
+        /// Initializes a new instance of the a <see cref="RutaModule"/> object
+        /// </summary>
         [ExcludeFromCodeCoverage]
         public RutaModule()
-            : this(new AdInteraction(), new SettingsWrapper())
-        {                
+            : this(new AdInteraction(), new SettingsWrapper(), new RutaTraceSource(nameof(RutaHttpModule)))
+        {            
         }
 
-        internal RutaModule(IAdInteraction adInteraction, ISettings settings)
+        /// <summary>
+        /// Initializes a new instance of the a <see cref="RutaModule"/> object
+        /// </summary>
+        /// <param name="adInteraction">Reference to the implementation needed to query the AD.</param>
+        /// <param name="settings">Reference to the settings needed for constructing the right header.</param>
+        /// <param name="traceSource">Reference to the tracing object.</param>
+        internal RutaModule(IAdInteraction adInteraction, ISettings settings, ITraceSource traceSource)
         {
             this.adInteraction = adInteraction ?? throw new ArgumentNullException(nameof(adInteraction));
             this.settings = settings ?? throw new ArgumentNullException(nameof(settings));
+            this.traceSource = traceSource ?? throw new ArgumentException(nameof(traceSource));
         }
 
-        [ExcludeFromCodeCoverage]
+        /// <summary>
+        /// The name of the module
+        /// </summary>
         public string ModuleName => "RutaModule";
 
-        // In the Init function, register for HttpApplication 
-        // events by adding your handlers.
-        [ExcludeFromCodeCoverage]
-        public void Init(HttpApplication application)
-        {
-            application.AuthorizeRequest += AuthorizeRequest;
-            this.traceSource = new TraceSource(nameof(RutaHttpModule)); // Do I need to do this here? https://www.iis.net/learn/develop/runtime-extensibility/how-to-add-tracing-to-iis-managed-modules
-        }
+        /// <summary>
+        /// Initializes a module and prepares it to handle requests (part of the <see cref="IHttpHandler"/> interface).
+        /// </summary>
+        /// <param name="application">An <see cref="HttpApplication"/> that provides access to the methods, properties, 
+        /// and events common to all application objects within an ASP.NET application</param>       
+        public void Init(HttpApplication application) => application.AuthorizeRequest += AuthorizeRequest;
 
-        [ExcludeFromCodeCoverage]
+        /// <summary>
+        /// Disposes of the resources (other than memory) used this module  (part of the <see cref="IHttpHandler"/> interface).
+        /// </summary>
         public void Dispose() { }
 
+        /// <summary>
+        /// Handler executed when a security module has verified user authorization. During execution of the handler the
+        /// httpContext will be changed.
+        /// </summary>
+        /// <param name="source">The source of the event.</param>
+        /// <param name="e">An object that contains no event data.</param>
         [ExcludeFromCodeCoverage]
         private void AuthorizeRequest(object source, EventArgs e)
+        {
+            var application = source as HttpApplication;
+            HandleAuthorizeRequest(new RutaHttpContext(application.Context));
+        }
+
+        /// <summary>
+        /// Handle an authorizeRequest using the <paramref name="context"/>.
+        /// </summary>
+        /// <param name="context">The context to be used when handling an AuthorizeRequest</param>
+        internal void HandleAuthorizeRequest(IRutaHttpContext context)
         {
             try
             {
-                traceSource.TraceEvent(TraceEventType.Start, 0, $"[{nameof(RutaModule)} MODULE] START AuthorizeRequest");
-
-                HttpApplication application = (HttpApplication)source;
-                AuthorizeRequest(new RutaHttpContext(application.Context));
+                traceSource.TraceEvent(TraceEventType.Start, 0, "START AuthorizeRequest");
+                HandleAuthorizeRequestInternal(context);
             }
-            catch(Exception ex)
+            catch (Exception ex)
             {
-                traceSource.TraceEvent(TraceEventType.Error, 0, $"[{nameof(RutaModule)} ERROR AuthorizeRequest: ExceptionData: '{ex}' ");
+                traceSource.TraceEvent(TraceEventType.Error, 0, $"ERROR AuthorizeRequest: ExceptionData: '{ex}' ");
                 throw;
             }
             finally
             {
-                traceSource.TraceEvent(TraceEventType.Stop, 0, $"[{nameof(RutaModule)} END AuthorizeRequest");
+                traceSource.TraceEvent(TraceEventType.Stop, 0, "END AuthorizeRequest");
             }
         }
 
-        // Internal for testing purposes
-        internal void AuthorizeRequest(IRutaHttpContext context)
+        /// <summary>
+        /// Replace the current context with a version that can be processed by SonarQube. That is done only 
+        /// if:<br/>
+        /// <ul>
+        ///   <li>The user is authenticated.</li>
+        ///   <li>The context contains a DomainUserName.</li>
+        ///   <li>The Ldap information could be extracted.</li>
+        ///   <li>The user information can be retrieved from AD.</li>
+        /// </ul>
+        /// </summary>
+        /// <param name="context">The context on which the action should be performed.</param>
+        private void HandleAuthorizeRequestInternal(IRutaHttpContext context)
         {
             if (!context.IsAuthenticated)
             {
+                traceSource.TraceEvent(TraceEventType.Information, 0, "Not authenticated");
                 return;
             }
 
             string userName = context.DomainUserName;
-
             if (string.IsNullOrWhiteSpace(userName))
             {
+                traceSource.TraceEvent(TraceEventType.Information, 0, "No username in context");
                 return;
             }
-
-            context.RemoveRequestHeader("Authorization"); // Remove the authorzation header since we are in charge of authentication
+            
             var userInformation = this.adInteraction.GetUserInformation(userName);
-
             if (string.IsNullOrWhiteSpace(userInformation.login))
             {
+                traceSource.TraceEvent(TraceEventType.Information, 0, "No user information in context");
                 return;
             }
 
-            string loginToSend = AppendIfNedded(DowncaseUserIfNeeded(userInformation.login));
-            string[] groupsToSend = userInformation.groups.Where(x => x != null).Select(DowncaseGroupIfNeeded).Select(AppendIfNedded).ToArray();
+            traceSource.TraceEvent(TraceEventType.Information, 0, "Set headers");
+
+            string loginToSend = ApplyUserSettings(userInformation.login);
+            string[] groupsToSend = userInformation.groups.Where(group => !string.IsNullOrWhiteSpace(group))
+                                                          .Select(ApplyGroupSettings)
+                                                          .ToArray();
 
+            context.RemoveRequestHeader("Authorization"); // Remove the authorzation header since we are in charge of authentication
             context.AddRequestHeader(this.settings.LoginHeader, loginToSend);
             context.AddRequestHeader(this.settings.NameHeader, userInformation.name);
             context.AddRequestHeader(this.settings.EmailHeader, userInformation.email);
             context.AddRequestHeader(this.settings.GroupsHeader, string.Join(",", groupsToSend));
         }
 
-        private string DowncaseGroupIfNeeded(string s)
-        {
-            if (!this.settings.DowncaseGroups)
-            {
-                return s;
-            }
-
-            return s.ToLower();
-        }
-
-        private string DowncaseUserIfNeeded(string s)
+        /// <summary>
+        /// Returns a copy of the <paramref name="group"/> object adjusted as necessary based on 
+        /// the settings (DowncaseGroups and AppendString).
+        /// </summary>
+        /// <param name="group">A <see cref="String"/> on which the action should be performed.</param>
+        /// <returns>The modified version of <paramref name="group"/>.</returns>
+        private string ApplyGroupSettings(string group) => AppendIfNeeded(LowercaseIfNeeded(group, this.settings.DowncaseGroups));
+
+        /// <summary>
+        /// Returns a copy of the <paramref name="user"/> object adjusted as necessary based on 
+        /// the settings (DowncaseUsers and AppendString).
+        /// </summary>
+        /// <param name="user">A <see cref="String"/> on which the action should be performed.</param>
+        /// <returns>The modified version of <paramref name="user"/>.</returns>
+        private string ApplyUserSettings(string user) => AppendIfNeeded(LowercaseIfNeeded(user, this.settings.DowncaseUsers));
+
+        /// <summary>
+        /// Returns a copy of the <paramref name="source"/> object appended with the contents of the
+        /// AppendString settings. The action will not be performed if <paramref name="source"/> or
+        /// AppendString are null or containing only whitespace. In all other cases <paramref name="source"/> 
+        /// will be returned.
+        /// </summary>
+        /// <param name="source">A <see cref="String"/> on which the action should be performed.</param>
+        /// <returns>The modified version of <paramref name="source"/>.</returns>
+        private string AppendIfNeeded(string source)
         {
-            if (!this.settings.DowncaseUsers)
+            if (string.IsNullOrWhiteSpace(this.settings.AppendString))
             {
-                return s;
+                return source;
             }
 
-            return s.ToLower();
+            return $"{source}{this.settings.AppendString}";
         }
 
-        private string AppendIfNedded(string s)
-        {
-            if (string.IsNullOrWhiteSpace(this.settings.AppendString) || string.IsNullOrWhiteSpace(s))
-            {
-                return s;
-            }
-
-            return $"{s}{this.settings.AppendString}";
-        }
+        /// <summary>
+        /// Returns a copy of the <paramref name="source"/> object converted to lowercase 
+        /// using the casing rules of the invariant culture if indicated by <paramref name="applyDowncase"/>. 
+        /// In all other cases <paramref name="source"/> will be returned.
+        /// </summary>
+        /// <param name="source">A <see cref="String"/> on which the action should be performed.</param>
+        /// <param name="applyLowercase">Should the method return a lowercase version of <paramref name="source"/>?</param>
+        /// <returns>The modified version of <paramref name="source"/>.</returns>
+        private static string LowercaseIfNeeded(string source, bool applyLowercase) => applyLowercase ? source.ToLowerInvariant() : source;
     }    
 }

RutaHttpModule/RutaTraceSource.cs

@@ -0,0 +1,46 @@
+namespace RutaHttpModule
+{
+    using System;
+    using System.Diagnostics;
+    using System.Diagnostics.CodeAnalysis;
+
+    /// <summary>
+    /// Wrapper class for using <see cref="TraceSource"/>.
+    /// </summary>
+    [ExcludeFromCodeCoverage]
+    internal class RutaTraceSource : ITraceSource
+    {
+        /// <summary>
+        /// The name of the trace source (typically, the name of the application).
+        /// </summary>
+        private readonly string tracesourceName;
+
+        /// <summary>
+        /// Internal <see cref="TraceSource"/> reference.
+        /// </summary>
+        private readonly TraceSource traceSource;
+
+        /// <summary>
+        /// Creates a <see cref="RutaTraceSource"/> based on the supplied
+        /// <paramref name="tracesourceName"/>.
+        /// </summary>
+        /// <param name="tracesourceName">The name of the trace source.</param>
+        internal RutaTraceSource(string tracesourceName)
+        {
+            this.traceSource = new TraceSource(tracesourceName);
+            this.tracesourceName = tracesourceName;         
+        }
+
+        /// <summary>
+        /// Writes a trace event message to the trace listeners using the specified event type, 
+        /// event identifier, and message.
+        /// </summary>
+        /// <param name="eventType">One of the enumeration values that specifies the event type of the trace data.</param>
+        /// <param name="id">An event identifier.</param>
+        /// <param name="message">The trace message to write.</param>
+        public void TraceEvent(TraceEventType eventType, int id, string message)
+        {
+            traceSource.TraceEvent(eventType, id, $"[{tracesourceName} MODULE] {message}");
+        }
+    }
+}

RutaHttpModuleTest/RutaHttpModuleTest.csproj

@@ -62,6 +62,7 @@
       <HintPath>..\packages\System.ValueTuple.4.3.0\lib\netstandard1.0\System.ValueTuple.dll</HintPath>
       <Private>True</Private>
     </Reference>
+    <Reference Include="System.Web" />
     <Reference Include="System.Xml" />
     <Reference Include="System.Xml.Linq" />
   </ItemGroup>