knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From m...@apache.org
Subject svn commit: r1782979 - in /knox: site/ site/books/knox-0-11-0/ site/books/knox-0-12-0/ trunk/books/0.11.0/dev-guide/ trunk/books/0.12.0/ trunk/books/0.12.0/dev-guide/
Date Tue, 14 Feb 2017 15:40:16 GMT
Author: more
Date: Tue Feb 14 15:40:16 2017
New Revision: 1782979

URL: http://svn.apache.org/viewvc?rev=1782979&view=rev
Log:
KNOX-870 - Documentation on supporting Custom Validators (Mohammad Kamrul Islam via Sandeep
More)

Modified:
    knox/site/books/knox-0-11-0/dev-guide.html
    knox/site/books/knox-0-12-0/dev-guide.html
    knox/site/books/knox-0-12-0/user-guide.html
    knox/site/index.html
    knox/site/issue-tracking.html
    knox/site/license.html
    knox/site/mail-lists.html
    knox/site/project-info.html
    knox/site/team-list.html
    knox/trunk/books/0.11.0/dev-guide/book.md
    knox/trunk/books/0.12.0/config_preauth_sso_provider.md
    knox/trunk/books/0.12.0/dev-guide/book.md

Modified: knox/site/books/knox-0-11-0/dev-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/dev-guide.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/books/knox-0-11-0/dev-guide.html (original)
+++ knox/site/books/knox-0-11-0/dev-guide.html Tue Feb 14 15:40:16 2017
@@ -13,7 +13,7 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
---><p><link href="book.css" rel="stylesheet"/></p><p><img src="knox-logo.gif"
alt="Knox"/> <img src="apache-logo.gif" align="right" alt="Apache"/></p><h1><a
id="Apache+Knox+Gateway+0.10.x+Developer's+Guide">Apache Knox Gateway 0.10.x Developer&rsquo;s
Guide</a> <a href="#Apache+Knox+Gateway+0.10.x+Developer's+Guide"><img src="markbook-section-link.png"/></a></h1><h2><a
id="Table+Of+Contents">Table Of Contents</a> <a href="#Table+Of+Contents"><img
src="markbook-section-link.png"/></a></h2>
+--><p><link href="book.css" rel="stylesheet"/></p><p><img src="knox-logo.gif"
alt="Knox"/> <img src="apache-logo.gif" align="right" alt="Apache"/></p><h1><a
id="Apache+Knox+Gateway+0.11.x+Developer's+Guide">Apache Knox Gateway 0.11.x Developer&rsquo;s
Guide</a> <a href="#Apache+Knox+Gateway+0.11.x+Developer's+Guide"><img src="markbook-section-link.png"/></a></h1><h2><a
id="Table+Of+Contents">Table Of Contents</a> <a href="#Table+Of+Contents"><img
src="markbook-section-link.png"/></a></h2>
 <ul>
   <li><a href="#Overview">Overview</a></li>
   <li><a href="#Architecture+Overview">Architecture Overview</a></li>

Modified: knox/site/books/knox-0-12-0/dev-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/dev-guide.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/dev-guide.html (original)
+++ knox/site/books/knox-0-12-0/dev-guide.html Tue Feb 14 15:40:16 2017
@@ -610,6 +610,93 @@ rewrite.xml
    protected void setReplayBufferSize(@Default(&quot;8&quot;) int size) {
       replayBufferSize = size;
    }
+</code></pre><h3><a id="Validator">Validator</a> <a href="#Validator"><img
src="markbook-section-link.png"/></a></h3><p>Apache Knox provides preauth
federation authentication where<br/>Knox supports two built-in validators for verifying
incoming requests. In this section, we describe how to write a custom validator for this scenario.
The provided validators include: </p>
+<ul>
+  <li><em>preauth.default.validation:</em> This default behavior does not
perform any validation check. All requests will pass.</li>
+  <li><em>preauth.ip.validation</em> : This validation checks if a request
is originated from an IP address which is configured in Knox service through property <em>preauth.ip.addresses</em>.</li>
+</ul><p>However, these built-in validation choices may not fulfill the internal
requirments of some organization. Therefore, Knox supports (since 0.12) a pluggble framework
where anyone can include a custom validator. </p><p>In essence, a user can add
a custom validator by following these steps. The corresponding code examples are incorporated
after that:</p>
+<ol>
+  <li>Create a separate Java package (e.g. com.company.knox.validator) in a new or
existing Maven project.</li>
+  <li>Create a new class (e.g. <em>CustomValidator</em>) that implements
<em>org.apache.hadoop.gateway.preauth.filter.PreAuthValidator</em>.</li>
+  <li>The class should implement the method <em>String getName()</em> that
may returns a string constant. The step-9 will need this user defined string constant.</li>
+  <li>The class should implement the method <em>boolean validate(HttpServletRequest
httpRequest, FilterConfig filterConfig)</em>. This is the key method which will validate
the request based on &lsquo;httpRequest&rsquo; and &lsquo;filterConfig&rsquo;.
In most common cases, user may need to use HTTP headers value to validate. For example, client
can get a token from an authentication service and pass it as HTTP header. This validate method
needs to extract that header and verify the token. In some instance, the server may need to
contact the same authentication service to validate.</li>
+  <li>Create a text file src/resources/META-INF/services and add fully qualified name
of your custom validator class (e.g. <em>com.company.knox.validator.CustomValidator</em>).</li>
+  <li>You may need to include the packages &ldquo;org.apache.knox.gateway-provider-security-preauth&rdquo;
of version 0.12+ and &ldquo;javax.servlet.javax.servlet-api&rdquo; of version 3.1.0+
in pom.xml.</li>
+  <li>Build your custom jar.</li>
+  <li>Deploy the jar in $GATEWAY_HOME/ext directory.</li>
+  <li>Add/modify a parameter called <em>preauth.validation.method</em>
with the name of validator used in step #3. Optionally, you may add any new parameter that
may be required only for your CustomValidator.</li>
+</ol><p><strong>Validator Class (Step 2-4)</strong> </p>
+<pre><code>package com.company.knox.validator;
+
+import org.apache.hadoop.gateway.preauth.filter.PreAuthValidationException;
+import org.apache.hadoop.gateway.preauth.filter.PreAuthValidator;
+import com.google.common.base.Strings;
+
+import javax.servlet.FilterConfig;
+import javax.servlet.http.HttpServletRequest;
+
+public class CustomValidator extends PreAuthValidator {
+  //Any string constant value should work for these 3 variables
+  //This string will be used in &#39;services&#39; file.
+  public static final String CUSTOM_VALIDATOR_NAME = &quot;fooValidator&quot;; 
+  //Optional: User may want to pass soemthign through HTTP header. (per client request)
+  public static final String CUSTOM_TOKEN_HEADER_NAME = &quot;foo_claim&quot;;
+
+
+  /**
+   * @param httpRequest
+   * @param filterConfig
+   * @return
+   * @throws PreAuthValidationException
+   */
+  @Override
+  public boolean validate(HttpServletRequest httpRequest, FilterConfig filterConfig) throws
PreAuthValidationException {
+    String claimToken = httpRequest.getHeader(CUSTOM_TOKEN_HEADER_NAME);
+    if (!Strings.isNullOrEmpty(claimToken)) {
+      return checkCustomeToken(claimToken); //to be implemented
+    } else {
+      log.warn(&quot;Claim token was empty for header name &#39;&quot; + CUSTOM_TOKEN_HEADER_NAME
+ &quot;&#39;&quot;);
+      return false;
+    }
+  }
+
+  /**
+   * Define unique validator name
+   *
+   * @return
+   */
+  @Override
+  public String getName() {
+    return CUSTOM_VALIDATOR_NAME;
+  }
+}
+</code></pre><p><strong>META-INF/services contents (Step-5)</strong></p><p><code>com.company.knox.validator.CustomValidator</code></p><p><strong>POM
file (Step-6)</strong></p>
+<pre><code>&lt;dependency&gt;
+    &lt;groupId&gt;javax.servlet&lt;/groupId&gt;
+    &lt;artifactId&gt;javax.servlet-api&lt;/artifactId&gt;
+    &lt;scope&gt;provided&lt;/scope&gt;
+&lt;/dependency&gt;
+
+&lt;dependency&gt;
+    &lt;groupId&gt;org.apache.knox&lt;/groupId&gt;
+    &lt;artifactId&gt;gateway-test-utils&lt;/artifactId&gt;
+    &lt;scope&gt;test&lt;/scope&gt;
+&lt;/dependency&gt;
+
+&lt;dependency&gt;
+    &lt;groupId&gt;org.apache.knox&lt;/groupId&gt;
+    &lt;artifactId&gt;gateway-provider-security-preauth&lt;/artifactId&gt;
+    &lt;scope&gt;provided&lt;/scope&gt;
+&lt;/dependency&gt;
+</code></pre><p><strong>Deploy Custom Jar (Step-7-8)</strong></p><p>Build
the jar (e.g. customValidation.jar) using &lsquo;mvn clean package&rsquo; <code>cp
customValidation.jar $GATEWAY_HOME/ext/</code></p><p><strong>Topology
Config (Step-9)</strong></p>
+<pre><code>&lt;provider&gt;
+    &lt;role&gt;federation&lt;/role&gt;
+    &lt;name&gt;HeaderPreAuth&lt;/name&gt;
+    &lt;enabled&gt;true&lt;/enabled&gt;
+    &lt;param&gt;&lt;name&gt;preauth.validation.method&lt;/name&gt;
+    &lt;!--Same as CustomeValidator.CUSTOM_VALIDATOR_NAME   -&gt;
+    &lt;value&gt;fooValidator&lt;/value&gt;&lt;/param&gt;
+&lt;/provider&gt;
 </code></pre><h3><a id="Providers">Providers</a> <a href="#Providers"><img
src="markbook-section-link.png"/></a></h3>
 <pre><code class="java">public interface ProviderDeploymentContributor {
   String getRole();

Modified: knox/site/books/knox-0-12-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/user-guide.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/user-guide.html (original)
+++ knox/site/books/knox-0-12-0/user-guide.html Tue Feb 14 15:40:16 2017
@@ -2435,8 +2435,8 @@ APACHE_HOME/bin/apachectl -k stop
   <tbody>
     <tr>
       <td>preauth.validation.method</td>
-      <td>Optional parameter that indicates the type of trust validation to perform
on incoming requests. Possible values are: null, preauth.ip.validation (others will be added
in future releases). Failure results in a 403 forbidden HTTP status response.</td>
-      <td>null - which means no validation will be performed and that we are assuming
that the network security and external authentication system is sufficient.</td>
+      <td>Optional parameter that indicates the type of trust validation to perform
on incoming requests. Possible values are: null, preauth.default.validation, preauth.ip.validation,
custom validator (details described in <a href="dev-guide.html#Validator">Custom Validator</a>).
Failure results in a 403 forbidden HTTP status response.</td>
+      <td>null - which means &lsquo;preauth.default.validation&rsquo; that
is no validation will be performed and that we are assuming that the network security and
external authentication system is sufficient.</td>
     </tr>
     <tr>
       <td>preauth.ip.addresses</td>

Modified: knox/site/index.html
URL: http://svn.apache.org/viewvc/knox/site/index.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Tue Feb 14 15:40:16 2017
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2017-02-10
+ | Generated by Apache Maven Doxia at 2017-02-14
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20170210" />
+    <meta name="Date-Revision-yyyymmdd" content="20170214" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; REST API Gateway for the Apache Hadoop Ecosystem</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2017-02-10</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2017-02-14</li>

             
                             </ul>
       </div>

Modified: knox/site/issue-tracking.html
URL: http://svn.apache.org/viewvc/knox/site/issue-tracking.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/issue-tracking.html (original)
+++ knox/site/issue-tracking.html Tue Feb 14 15:40:16 2017
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2017-02-10
+ | Generated by Apache Maven Doxia at 2017-02-14
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20170210" />
+    <meta name="Date-Revision-yyyymmdd" content="20170214" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Issue Tracking</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2017-02-10</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2017-02-14</li>

             
                             </ul>
       </div>

Modified: knox/site/license.html
URL: http://svn.apache.org/viewvc/knox/site/license.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/license.html (original)
+++ knox/site/license.html Tue Feb 14 15:40:16 2017
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2017-02-10
+ | Generated by Apache Maven Doxia at 2017-02-14
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20170210" />
+    <meta name="Date-Revision-yyyymmdd" content="20170214" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Project License</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2017-02-10</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2017-02-14</li>

             
                             </ul>
       </div>

Modified: knox/site/mail-lists.html
URL: http://svn.apache.org/viewvc/knox/site/mail-lists.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/mail-lists.html (original)
+++ knox/site/mail-lists.html Tue Feb 14 15:40:16 2017
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2017-02-10
+ | Generated by Apache Maven Doxia at 2017-02-14
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20170210" />
+    <meta name="Date-Revision-yyyymmdd" content="20170214" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Project Mailing Lists</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2017-02-10</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2017-02-14</li>

             
                             </ul>
       </div>

Modified: knox/site/project-info.html
URL: http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Tue Feb 14 15:40:16 2017
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2017-02-10
+ | Generated by Apache Maven Doxia at 2017-02-14
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20170210" />
+    <meta name="Date-Revision-yyyymmdd" content="20170214" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Project Information</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2017-02-10</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2017-02-14</li>

             
                             </ul>
       </div>

Modified: knox/site/team-list.html
URL: http://svn.apache.org/viewvc/knox/site/team-list.html?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/site/team-list.html (original)
+++ knox/site/team-list.html Tue Feb 14 15:40:16 2017
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2017-02-10
+ | Generated by Apache Maven Doxia at 2017-02-14
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="Date-Revision-yyyymmdd" content="20170210" />
+    <meta name="Date-Revision-yyyymmdd" content="20170214" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Knox Gateway &#x2013; Team list</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -58,7 +58,7 @@
               
                 
                     
-                  <li id="publishDate" class="pull-right">Last Published: 2017-02-10</li>

+                  <li id="publishDate" class="pull-right">Last Published: 2017-02-14</li>

             
                             </ul>
       </div>

Modified: knox/trunk/books/0.11.0/dev-guide/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/dev-guide/book.md?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/trunk/books/0.11.0/dev-guide/book.md (original)
+++ knox/trunk/books/0.11.0/dev-guide/book.md Tue Feb 14 15:40:16 2017
@@ -20,7 +20,7 @@
 <img src="knox-logo.gif" alt="Knox"/>
 <img src="apache-logo.gif" align="right" alt="Apache"/>
 
-# Apache Knox Gateway 0.10.x Developer's Guide #
+# Apache Knox Gateway 0.11.x Developer's Guide #
 
 ## Table Of Contents ##
 * #[Overview]

Modified: knox/trunk/books/0.12.0/config_preauth_sso_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/config_preauth_sso_provider.md?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/config_preauth_sso_provider.md (original)
+++ knox/trunk/books/0.12.0/config_preauth_sso_provider.md Tue Feb 14 15:40:16 2017
@@ -41,7 +41,7 @@ The following table describes the config
 
 Name | Description | Default
 ---------|-----------
-preauth.validation.method|Optional parameter that indicates the type of trust validation
to perform on incoming requests. Possible values are: null, preauth.ip.validation (others
will be added in future releases). Failure results in a 403 forbidden HTTP status response.|null
- which means no validation will be performed and that we are assuming that the network security
and external authentication system is sufficient.  
+preauth.validation.method|Optional parameter that indicates the type of trust validation
to perform on incoming requests. Possible values are: null, preauth.default.validation, preauth.ip.validation,
custom validator (details described in [Custom Validator](dev-guide.html#Validator)). Failure
results in a 403 forbidden HTTP status response.|null - which means 'preauth.default.validation'
that is  no validation will be performed and that we are assuming that the network security
and external authentication system is sufficient. 
 preauth.ip.addresses|Optional parameter that indicates the list of trusted ip addresses.
When preauth.ip.validation is indicated as the validation method this parameter must be provided
to indicate the trusted ip address set. Wildcarded IPs may be used to indicate subnet level
trust. ie. 127.0.*|null - which means that no validation will be performed.
 preauth.custom.header|Required parameter for indicating a custom header to use for extracting
the preauthenticated principal. The value extracted from this header is utilized as the PrimaryPrincipal
within the established Subject. An incoming request that is missing the configured header
will be refused with a 401 unauthorized HTTP status.|SM_USER for SiteMinder usecase
 preauth.custom.group.header|Optional parameter for indicating a HTTP header name that contains
a comma separated list of groups. These are added to the authenticated Subject as group principals.
A missing group header will result in no groups being extracted from the incoming request
and a log entry but processing will continue.|null - which means that there will be no group
principals extracted from the request and added to the established Subject.

Modified: knox/trunk/books/0.12.0/dev-guide/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/dev-guide/book.md?rev=1782979&r1=1782978&r2=1782979&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/dev-guide/book.md (original)
+++ knox/trunk/books/0.12.0/dev-guide/book.md Tue Feb 14 15:40:16 2017
@@ -1002,6 +1002,118 @@ org.apache.hadoop.gateway.dispatch.Defau
    }
 ```
 
+### Validator ###
+Apache Knox provides preauth federation authentication where  
+Knox supports two built-in validators for verifying incoming requests. In this section, we
describe how to write a custom validator for this scenario. The provided validators include:

+
+*  *preauth.default.validation:* This default behavior does not perform any validation check.
All requests will pass.
+*  *preauth.ip.validation* : This validation checks if a request is originated from an IP
address which is configured in Knox service through property *preauth.ip.addresses*.
+
+However, these built-in validation choices may not fulfill the internal requirments of some
organization. Therefore, Knox supports (since 0.12) a pluggble framework where anyone can
include a custom validator. 
+
+In essence, a user can add a custom validator by following these  steps. The corresponding
code examples are incorporated after that:
+ 
+1. Create a separate Java package (e.g. com.company.knox.validator) in a new or existing
Maven project.
+2. Create a new class (e.g. *CustomValidator*) that implements *org.apache.hadoop.gateway.preauth.filter.PreAuthValidator*.
+3. The class should implement the method *String getName()* that may returns a string constant.
The step-9  will need this user defined string constant.
+4. The class should implement the method *boolean validate(HttpServletRequest httpRequest,
FilterConfig filterConfig)*. This is the key method which will validate the request based
on 'httpRequest' and 'filterConfig'. In most common cases, user may need to use HTTP headers
value to validate. For example, client can get a token from an authentication service and
pass it as HTTP header. This validate method needs to extract that header and verify the token.
In some instance, the server may need to contact the same authentication service to validate.
+5. Create a text file src/resources/META-INF/services and add fully qualified name of your
custom validator class (e.g. *com.company.knox.validator.CustomValidator*).
+6. You may need to include the packages "org.apache.knox.gateway-provider-security-preauth"
 of version 0.12+ and  "javax.servlet.javax.servlet-api" of version 3.1.0+ in pom.xml.
+7. Build your custom jar.
+8. Deploy the jar in $GATEWAY_HOME/ext directory.
+9. Add/modify a parameter called *preauth.validation.method* with the name of validator used
in step #3. Optionally, you may add any new parameter that may be required only for your CustomValidator.
+
+**Validator Class (Step 2-4)** 
+
+	package com.company.knox.validator;
+	
+	import org.apache.hadoop.gateway.preauth.filter.PreAuthValidationException;
+	import org.apache.hadoop.gateway.preauth.filter.PreAuthValidator;
+	import com.google.common.base.Strings;
+	
+	import javax.servlet.FilterConfig;
+	import javax.servlet.http.HttpServletRequest;
+	
+	public class CustomValidator extends PreAuthValidator {
+	  //Any string constant value should work for these 3 variables
+	  //This string will be used in 'services' file.
+	  public static final String CUSTOM_VALIDATOR_NAME = "fooValidator"; 
+	  //Optional: User may want to pass soemthign through HTTP header. (per client request)
+	  public static final String CUSTOM_TOKEN_HEADER_NAME = "foo_claim";
+	   
+	  
+	  /**
+	   * @param httpRequest
+	   * @param filterConfig
+	   * @return
+	   * @throws PreAuthValidationException
+	   */
+	  @Override
+	  public boolean validate(HttpServletRequest httpRequest, FilterConfig filterConfig) throws
PreAuthValidationException {
+	    String claimToken = httpRequest.getHeader(CUSTOM_TOKEN_HEADER_NAME);
+	    if (!Strings.isNullOrEmpty(claimToken)) {
+	      return checkCustomeToken(claimToken); //to be implemented
+	    } else {
+	      log.warn("Claim token was empty for header name '" + CUSTOM_TOKEN_HEADER_NAME + "'");
+	      return false;
+	    }
+	  }
+	
+	  /**
+	   * Define unique validator name
+	   *
+	   * @return
+	   */
+	  @Override
+	  public String getName() {
+	    return CUSTOM_VALIDATOR_NAME;
+	  }
+	}
+	
+
+**META-INF/services contents (Step-5)**
+
+`com.company.knox.validator.CustomValidator`
+
+
+**POM file (Step-6)**
+
+    <dependency>
+        <groupId>javax.servlet</groupId>
+        <artifactId>javax.servlet-api</artifactId>
+        <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>org.apache.knox</groupId>
+        <artifactId>gateway-test-utils</artifactId>
+        <scope>test</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>org.apache.knox</groupId>
+        <artifactId>gateway-provider-security-preauth</artifactId>
+        <scope>provided</scope>
+    </dependency>
+
+
+**Deploy Custom Jar (Step-7-8)**
+
+Build the jar (e.g. customValidation.jar) using 'mvn clean package'
+`cp customValidation.jar $GATEWAY_HOME/ext/`
+
+**Topology Config (Step-9)**
+
+
+    <provider>
+        <role>federation</role>
+        <name>HeaderPreAuth</name>
+        <enabled>true</enabled>
+        <param><name>preauth.validation.method</name>
+        <!--Same as CustomeValidator.CUSTOM_VALIDATOR_NAME   ->
+        <value>fooValidator</value></param>
+    </provider>
+
 ### Providers ###
 
 ```java



Mime
View raw message