From 1fb1508e88559cf09b8fe1ea8b97f69b8650be9e Mon Sep 17 00:00:00 2001
From: Bill Bagdon <wbagdon@gmail.com>
Date: Thu, 15 Mar 2018 17:03:35 -0400
Subject: [PATCH] Update docs for exclusion filter

---
 Docs/ServletSingleSignOnSecurityFilter.md | 10 +++++++-
 Docs/faq/AtlassianJIRA.md                 | 30 +++++++++++++++++++++--
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/Docs/ServletSingleSignOnSecurityFilter.md b/Docs/ServletSingleSignOnSecurityFilter.md
index 5147bb9c15..943d46301d 100644
--- a/Docs/ServletSingleSignOnSecurityFilter.md
+++ b/Docs/ServletSingleSignOnSecurityFilter.md
@@ -10,7 +10,7 @@ Configuring Web Servers
 
 The following steps are required to configure a web server with the Waffle Servlet Security Filter. These instructions work for Tomcat, Jetty, WebSphere and possibly others.
 
-Package Waffle JARs (1.8.2), including `waffle-jna-1.8.2.jar`, `guava-20.0.jar`, `jna-4.2.2.jar`, `jna-platform-4.2.2.jar` and `slf4j-1.7.22.jar` in the application's `lib` directory or copy them to your web server's lib. 
+Package Waffle JARs (1.8.4), including `waffle-jna-1.8.4.jar`, `guava-20.0.jar`, `jna-4.3.0.jar`, `jna-platform-4.3.0.jar` and `slf4j-1.7.22.jar` in the application's `lib` directory or copy them to your web server's lib. 
 
 - For latest snapshot instead use `waffle-jna-1.9.0-SNAPSHOT`, `caffeine-2.3.5.jar`, `jna-4.3.0.jar`, `jna-platform-4.3.0.jar` and `slf4j-1.7.22.jar`.
 
@@ -40,6 +40,7 @@ The filter can be configured with the following `init-param` options.
 * waffle.servlet.spi.NegotiateSecurityFilterProvider/protocols: A list of security protocols supported by the `NegotiateSecurityFilterProvider`. Can be one of or a combination of Negotiate and NTLM. 
 * waffle.servlet.spi.BasicSecurityFilterProvider/realm: The name of the Realm for BASIC authentication. 
 * impersonate: Allow impersonation. When true the remote user will be impersonated. Note that there is no mapping between the Windows native threads, under which the impersonation takes place, and the Java threads. Thus you'll need to use Windows native APIs to perform impersonated actions. Any action done in Java will still be performed with the user account running the servlet container. 
+* excludePatterns: Url patterns to exclude from the filter, uses regex for pattern matching
 
 Filter Configuration Example
 ----------------------------
@@ -64,6 +65,13 @@ Filter Configuration Example
       <param-name>impersonate</param-name>
       <param-value>true</param-value>
   </init-param>
+  <init-param>
+      <param-name>excludePatterns</param-name>
+      <param-value>
+        .*/rest/.*
+        .*/api/v2/.*
+      </param-value>
+  </init-param>
   <init-param>
       <param-name>securityFilterProviders</param-name>
       <param-value>
diff --git a/Docs/faq/AtlassianJIRA.md b/Docs/faq/AtlassianJIRA.md
index 63edffdb46..0574b183e5 100644
--- a/Docs/faq/AtlassianJIRA.md
+++ b/Docs/faq/AtlassianJIRA.md
@@ -4,10 +4,37 @@
 
 Yes. Follow the [Servlet Filter Configuration Instructions](https://github.com/dblock/waffle/blob/master/Docs/ServletSingleSignOnSecurityFilter.md). 
 
+Tested with Jira 7.6.3
+
 * Deploy libs into tomcat's lib or application's `WEB-INF/lib`.
+  * slf4j-1.7.22.jar can be excluded as a newer version is bundled with JIRA.
 * Update `WEB-INF/web.xml` with `filter` and `filter-mapping`. 
   * Place the 'filter' before the last filter of JIRA, ie. `JiraLastFilter`.
-  * Place the 'filter-mapping' before the last filter-mapping of JIRA, i.e. `JiraLastFilter`.
+    ```xml
+    <filter>
+        <filter-name>SecurityFilter</filter-name>
+        <filter-class>waffle.servlet.NegotiateSecurityFilter</filter-class>
+        <init-param>
+            <param-name>excludePatterns</param-name>
+            <param-value>
+                .*/rest/.*
+                .*/secure/CreateIssue.*
+                .*/secure/QuickCreateIssue.*
+            </param-value>
+        </init-param>
+    </filter>
+    ```
+  * Place the 'filter-mapping' before the login filter-mapping of JIRA.
+    ```xml
+    <filter-mapping>
+        <filter-name>SecurityFilter</filter-name>
+        <url-pattern>/</url-pattern>
+        <url-pattern>/*</url-pattern>
+        <dispatcher>REQUEST</dispatcher>
+        <dispatcher>FORWARD</dispatcher>
+        <dispatcher>POST</dispatcher>
+    </filter-mapping>
+    ```
 * Update `seraph-config.xml` to use a custom authenticator, [RemoteUserJiraAuth](https://marketplace.atlassian.com/plugins/anguswarren.jira.RemoteUserJiraAuth). Modification may be needed.
   * [Source](https://github.com/AngusWarren/remoteuserauth)
   * [Modification](https://github.com/AngusWarren/remoteuserauth/pull/6/files)
@@ -23,4 +50,3 @@ Yes, log out and click log back in, this should bring up the login portal to log
 ## I'm not seeing the startup page or my gadgets are not displaying properly
 
 Check the location of your filter-mapping and make sure it is exactly before the filter mapping `JiraLastFilter`
-