You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by mo...@apache.org on 2017/02/10 16:31:09 UTC
svn commit: r1782487 [8/12] - in /knox: site/books/knox-0-12-0/
trunk/books/0.12.0/ trunk/books/0.12.0/dev-guide/
Added: knox/trunk/books/0.12.0/config_pac4j_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/config_pac4j_provider.md?rev=1782487&view=auto
==============================================================================
--- knox/trunk/books/0.12.0/config_pac4j_provider.md (added)
+++ knox/trunk/books/0.12.0/config_pac4j_provider.md Fri Feb 10 16:31:08 2017
@@ -0,0 +1,197 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ 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.
+--->
+
+### Pac4j Provider - CAS / OAuth / SAML / OpenID Connect ###
+
+<p align="center">
+ <img src="https://pac4j.github.io/pac4j/img/logo-knox.png" width="300" />
+</p>
+
+[pac4j](https://github.com/pac4j/pac4j) is a Java security engine to authenticate users, get their profiles and manage their authorizations in order to secure Java web applications.
+
+It supports many authentication mechanisms for UI and web services and is implemented by many frameworks and tools.
+
+For Knox, it is used as a federation provider to support the OAuth, CAS, SAML and OpenID Connect protocols. It must be used for SSO, in association with the KnoxSSO service and optionally with the SSOCookieProvider for access to REST APIs.
+
+
+#### Configuration ####
+##### SSO topology #####
+
+To enable SSO for REST API access through the Knox gateway, you need to protect your Hadoop services with the the SSOCookieProvider configured to use the KnoxSSO service (sandbox.xml topology):
+
+ <gateway>
+ <provider>
+ <role>webappsec</role>
+ <name>WebAppSec</name>
+ <enabled>true</enabled>
+ <param>
+ <name>cors.enabled</name>
+ <value>true</value>
+ </param>
+ </provider>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://127.0.0.1:8443/gateway/knoxsso/api/v1/websso</value>
+ </param>
+ </provider>
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ </provider>
+ </gateway>
+
+ <service>
+ <role>NAMENODE</role>
+ <url>hdfs://localhost:8020</url>
+ </service>
+
+ ...
+
+and protect the KnoxSSO service by the pac4j provider (knoxsso.xml topology):
+
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>pac4j</name>
+ <enabled>true</enabled>
+ <param>
+ <name>pac4j.callbackUrl</name>
+ <value>https://127.0.0.1:8443/gateway/knoxsso/api/v1/websso</value>
+ </param>
+ <param>
+ <name>cas.loginUrl</name>
+ <value>https://casserverpac4j.herokuapp.com/login</value>
+ </param>
+ </provider>
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ </provider>
+ </gateway>
+
+ <service>
+ <role>KNOXSSO</role>
+ <param>
+ <name>knoxsso.cookie.secure.only</name>
+ <value>true</value>
+ </param>
+ <param>
+ <name>knoxsso.token.ttl</name>
+ <value>100000</value>
+ </param>
+ <param>
+ <name>knoxsso.redirect.whitelist.regex</name>
+ <value>^https?:\/\/(localhost|127\.0\.0\.1|0:0:0:0:0:0:0:1|::1):[0-9].*$</value>
+ </param>
+ </service>
+
+Notice that the pac4j callback url is the KnoxSSO url (`pac4j.callbackUrl` parameter). An additional `pac4j.cookie.domain.suffix` parameter allows you to define the domain suffix for the pac4j cookies.
+
+In this example, the pac4j provider is configured to authenticate users via a CAS server hosted at: https://casserverpac4j.herokuapp.com/login.
+
+##### Parameters #####
+
+You can define the identity provider client/s to be used for authentication with the appropriate parameters - as defined below.
+When configuring any pac4j identity provider client there is a mandatory parameter that must be defined to indicate the order in which the providers should be engaged with the first in the comma separated list being the default. Consuming applications may indicate their desire to use one of the configured clients with a query parameter called client_name. When there is no client_name specified, the default (first) provider is selected.
+
+ <param>
+ <name>clientName</name>
+ <value>CLIENTNAME[,CLIENTNAME]</value>
+ </param>
+
+Valid client names are: `FacebookClient`, `TwitterClient`, `CasClient`, `SAML2Client` or `OidcClient`
+
+For tests only, you can use a basic authentication where login equals password by defining the following configuration:
+
+ <param>
+ <name>clientName</name>
+ <value>testBasicAuth</value>
+ </param>
+
+NOTE: This is NOT a secure mechanism and must NOT be used in production deployments.
+
+Otherwise, you can use Facebook, Twitter, a CAS server, a SAML IdP or an OpenID Connect provider by using the following parameters:
+
+##### For OAuth support:
+
+Name | Value
+-----|------
+facebook.id | Identifier of the OAuth Facebook application
+facebook.secret | Secret of the OAuth Facebook application
+facebook.scope | Requested scope at Facebook login
+facebook.fields | Fields returned by Facebook
+twitter.id | Identifier of the OAuth Twitter application
+twitter.secret | Secret of the OAuth Twitter application
+
+##### For CAS support:
+
+Name | Value
+-----|------
+cas.loginUrl | Login url of the CAS server
+cas.protocol | CAS protocol (`CAS10`, `CAS20`, `CAS20_PROXY`, `CAS30`, `CAS30_PROXY`, `SAML`)
+
+##### For SAML support:
+
+Name | Value
+-----|------
+saml.keystorePassword | Password of the keystore (storepass)
+saml.privateKeyPassword | Password for the private key (keypass)
+saml.keystorePath | Path of the keystore
+saml.identityProviderMetadataPath | Path of the identity provider metadata
+saml.maximumAuthenticationLifetime | Maximum lifetime for authentication
+saml.serviceProviderEntityId | Identifier of the service provider
+saml.serviceProviderMetadataPath | Path of the service provider metadata
+
+> Get more details on the [pac4j wiki](https://github.com/pac4j/pac4j/wiki/Clients#saml-support).
+
+The SSO url in your SAML 2 provider config will need to include a special query parameter that lets the pac4j provider know that the request is coming back from the provider rather than from a redirect from a KnoxSSO participating application. This query parameter is "pac4jCallback=true".
+
+This results in a URL that looks something like:
+
+ https://hostname:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client
+
+This also means that the SP Entity ID should also include this query parameter as appropriate for your provider.
+Often something like the above URL is used for both the SSO url and SP Entity ID.
+
+##### For OpenID Connect support:
+
+Name | Value
+-----|------
+oidc.id | Identifier of the OpenID Connect provider
+oidc.secret | Secret of the OpenID Connect provider
+oidc.discoveryUri | Direcovery URI of the OpenID Connect provider
+oidc.useNonce | Whether to use nonce during login process
+oidc.preferredJwsAlgorithm | Preferred JWS algorithm
+oidc.maxClockSkew | Max clock skew during login process
+oidc.customParamKey1 | Key of the first custom parameter
+oidc.customParamValue1 | Value of the first custom parameter
+oidc.customParamKey2 | Key of the second custom parameter
+oidc.customParamValue2 | Value of the second custom parameter
+
+> Get more details on the [pac4j wiki](https://github.com/pac4j/pac4j/wiki/Clients#openid-connect-support).
+
+In fact, you can even define several identity providers at the same time, the first being chosen by default unless you define a `client_name` parameter to specify it (`FacebookClient`, `TwitterClient`, `CasClient`, `SAML2Client` or `OidcClient`).
+
+##### UI invocation
+
+In a browser, when calling your Hadoop service (for example: `https://127.0.0.1:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS`), you are redirected to the identity provider for login. Then, after a successful authentication, your are redirected back to your originally requested url and your KnoxSSO session is initialized.
Added: knox/trunk/books/0.12.0/config_pam_authn.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/config_pam_authn.md?rev=1782487&view=auto
==============================================================================
--- knox/trunk/books/0.12.0/config_pam_authn.md (added)
+++ knox/trunk/books/0.12.0/config_pam_authn.md Fri Feb 10 16:31:08 2017
@@ -0,0 +1,83 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ 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.
+--->
+
+### PAM based Authentication ###
+
+There is a large number of pluggable authentication modules available on many linux installations and from vendors of authentication solutions that are great to leverage for authenticating access to Hadoop through the Knox Gateway. In addition to LDAP support described in this guide, the ShiroProvider also includes support for PAM based authentication for unix based systems.
+
+This opens up the integration possibilities to many other readily available authentication mechanisms as well as other implementations for LDAP based authentication. More flexibility may be available through various PAM modules for group lookup, more complicated LDAP schemas or other areas where the KnoxLdapRealm is not sufficient.
+
+#### Configuration ####
+##### Overview #####
+The primary motivation for leveraging PAM based authentication is to provide the ability to use the configuration provided by existing PAM modules that are available in a system's /etc/pam.d/ directory. Therefore, the solution provided here is as simple as possible in order to allow the PAM module config itself to be the source of truth. What we do need to configure is the fact that we are using PAM through the main.pamRealm parameter and the KnoxPamRealm classname and the particular PAM module to use with the main.pamRealm.service parameter in the below example we have 'login'.
+
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+ <param>
+ <name>main.pamRealm</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxPamRealm</value>
+ </param>
+ <param>
+ <name>main.pamRealm.service</name>
+ <value>login</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</value>
+ </param>
+ </provider>
+
+
+As a non-normative example of a PAM config file see the below from my macbook /etc/pam.d/login:
+
+ # login: auth account password session
+ auth optional pam_krb5.so use_kcminit
+ auth optional pam_ntlm.so try_first_pass
+ auth optional pam_mount.so try_first_pass
+ auth required pam_opendirectory.so try_first_pass
+ account required pam_nologin.so
+ account required pam_opendirectory.so
+ password required pam_opendirectory.so
+ session required pam_launchd.so
+ session required pam_uwtmp.so
+ session optional pam_mount.so
+
+The first four fields are: service-name, module-type, control-flag and module-filename. The fifth and greater fields are for optional arguments that are specific to the individual authentication modules.
+
+The second field in the configuration file is the module-type, it indicates which of the four PAM management services the corresponding module will provide to the application. Our sample configuration file refers to all four groups:
+
+* auth: identifies the PAMs that are invoked when the application calls pam_authenticate() and pam_setcred().
+* account: maps to the pam_acct_mgmt() function.
+* session: indicates the mapping for the pam_open_session() and pam_close_session() calls.
+* password: group refers to the pam_chauthtok() function.
+
+Generally, you only need to supply mappings for the functions that are needed by a specific application. For example, the standard password changing application, passwd, only requires a password group entry; any other entries are ignored.
+
+The third field indicates what action is to be taken based on the success or failure of the corresponding module. Choices for tokens to fill this field are:
+
+* requisite: Failure instantly returns control to the application indicating the nature of the first module failure.
+* required: All these modules are required to succeed for libpam to return success to the application.
+* sufficient: Given that all preceding modules have succeeded, the success of this module leads to an immediate and successful return to the application (failure of this module is ignored).
+* optional: The success or failure of this module is generally not recorded.
+
+The fourth field contains the name of the loadable module, pam_*.so. For the sake of readability, the full pathname of each module is not given. Before Linux-PAM-0.56 was released, there was no support for a default authentication-module directory. If you have an earlier version of Linux-PAM installed, you will have to specify the full path for each of the modules. Your distribution most likely placed these modules exclusively in one of the following directories: /lib/security/ or /usr/lib/security/.
\ No newline at end of file
Added: 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=1782487&view=auto
==============================================================================
--- knox/trunk/books/0.12.0/config_preauth_sso_provider.md (added)
+++ knox/trunk/books/0.12.0/config_preauth_sso_provider.md Fri Feb 10 16:31:08 2017
@@ -0,0 +1,87 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ 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.
+--->
+
+### Preauthenticated SSO Provider ###
+
+A number of SSO solutions provide mechanisms for federating an authenticated identity across applications. These mechanisms are at times simple HTTP Header type tokens that can be used to propagate the identity across process boundaries.
+
+Knox Gateway needs a pluggable mechanism for consuming these tokens and federating the asserted identity through an interaction with the Hadoop cluster.
+
+**CAUTION: The use of this provider requires that proper network security and identity provider configuration and deployment does not allow requests directly to the Knox gateway. Otherwise, this provider will leave the gateway exposed to identity spoofing.**
+
+#### Configuration ####
+##### Overview #####
+This provider was designed for use with identity solutions such as those provided by CA's SiteMinder and IBM's Tivoli Access Manager. While direct testing with these products has not been done, there has been extensive unit and functional testing that ensure that it should work with such providers.
+
+The HeaderPreAuth provider is configured within the topology file and has a minimal configuration that assumes SM_USER for CA SiteMinder. The following example is the bare minimum configuration for SiteMinder (with no IP address validation).
+
+ <provider>
+ <role>federation</role>
+ <name>HeaderPreAuth</name>
+ <enabled>true</enabled>
+ </provider>
+
+The following table describes the configuration options for the web app security provider:
+
+##### Descriptions #####
+
+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.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.
+
+NOTE: Mutual authentication can be used to establish a strong trust relationship between clients and servers while using the Preauthenticated SSO provider. See the configuration for Mutual Authentication with SSL in this document.
+
+##### Configuration for SiteMinder
+The following is an example of a configuration of the preauthenticated sso provider that leverages the default SM_USER header name - assuming use with CA SiteMinder. It further configures the validation based on the IP address from the incoming request.
+
+ <provider>
+ <role>federation</role>
+ <name>HeaderPreAuth</name>
+ <enabled>true</enabled>
+ <param><name>preauth.validation.method</name><value>preauth.ip.validation</value></param>
+ <param><name>preauth.ip.addresses</name><value>127.0.0.2,127.0.0.1</value></param>
+ </provider>
+
+##### REST Invocation for SiteMinder
+The following curl command can be used to request a directory listing from HDFS while passing in the expected header SM_USER.
+
+ curl -k -i --header "SM_USER: guest" -v https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS
+
+Omitting the --header "SM_USER: guest" above will result in a rejected request.
+
+##### Configuration for IBM Tivoli AM
+As an example for configuring the preauthenticated SSO provider for another SSO provider, the following illustrates the values used for IBM's Tivoli Access Manager:
+
+ <provider>
+ <role>federation</role>
+ <name>HeaderPreAuth</name>
+ <enabled>true</enabled>
+ <param><name>preauth.custom.header</name><value>iv_user</value></param>
+ <param><name>preauth.custom.group.header</name><value>iv_group</value></param>
+ <param><name>preauth.validation.method</name><value>preauth.ip.validation</value></param>
+ <param><name>preauth.ip.addresses</name><value>127.0.0.2,127.0.0.1</value></param>
+ </provider>
+
+##### REST Invocation for Tivoli AM
+The following curl command can be used to request a directory listing from HDFS while passing in the expected headers of iv_user and iv_group. Note that the iv_group value in this command matches the expected ACL for webhdfs in the above topology file. Changing this from "admin" to "admin2" should result in a 401 unauthorized response.
+
+ curl -k -i --header "iv_user: guest" --header "iv_group: admin" -v https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS
+
+Omitting the --header "iv_user: guest" above will result in a rejected request.
Added: knox/trunk/books/0.12.0/config_sandbox.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/config_sandbox.md?rev=1782487&view=auto
==============================================================================
--- knox/trunk/books/0.12.0/config_sandbox.md (added)
+++ knox/trunk/books/0.12.0/config_sandbox.md Fri Feb 10 16:31:08 2017
@@ -0,0 +1,51 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ 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.
+--->
+
+## Sandbox Configuration ##
+
+### Sandbox 2.x Configuration ###
+
+TODO
+
+### Sandbox 1.x Configuration ###
+
+TODO - Update this section to use hostmap if that simplifies things.
+
+This version of the Apache Knox Gateway is tested against [Hortonworks Sandbox 1.x][sandbox]
+
+Currently there is an issue with Sandbox that prevents it from being easily used with the gateway.
+In order to correct the issue, you can use the commands below to login to the Sandbox VM and modify the configuration.
+This assumes that the name sandbox is setup to resolve to the Sandbox VM.
+It may be necessary to use the IP address of the Sandbox VM instead.
+*This is frequently but not always `192.168.56.101`.*
+
+ ssh root@sandbox
+ cp /usr/lib/hadoop/conf/hdfs-site.xml /usr/lib/hadoop/conf/hdfs-site.xml.orig
+ sed -e s/localhost/sandbox/ /usr/lib/hadoop/conf/hdfs-site.xml.orig > /usr/lib/hadoop/conf/hdfs-site.xml
+ shutdown -r now
+
+In addition to make it very easy to follow along with the samples for the gateway you can configure your local system to resolve the address of the Sandbox by the names `vm` and `sandbox`.
+The IP address that is shown below should be that of the Sandbox VM as it is known on your system.
+*This will likely, but not always, be `192.168.56.101`.*
+
+On Linux or Macintosh systems add a line like this to the end of the file `/etc/hosts` on your local machine, *not the Sandbox VM*.
+_Note: The character between the 192.168.56.101 and vm below is a *tab* character._
+
+ 192.168.56.101 vm sandbox
+
+On Windows systems a similar but different mechanism can be used. On recent
+versions of windows the file that should be modified is `%systemroot%\system32\drivers\etc\hosts`
Added: knox/trunk/books/0.12.0/config_webappsec_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/config_webappsec_provider.md?rev=1782487&view=auto
==============================================================================
--- knox/trunk/books/0.12.0/config_webappsec_provider.md (added)
+++ knox/trunk/books/0.12.0/config_webappsec_provider.md Fri Feb 10 16:31:08 2017
@@ -0,0 +1,106 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ 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.
+--->
+
+### Web App Security Provider ###
+Knox is a Web API (REST) Gateway for Hadoop. The fact that REST interactions are HTTP based means that they are vulnerable to a number of web application security vulnerabilities. This project introduces a web application security provider for plugging in various protection filters.
+
+There are two aspects of web application security that are handled now: Cross Site Request Forgery (CSRF) and Cross Origin Resource Sharing. Others will be added in future releases.
+
+#### CSRF
+Cross site request forgery (CSRF) attacks attempt to force an authenticated user to
+execute functionality without their knowledge. By presenting them with a link or image that when clicked invokes a request to another site with which the user may have already established an active session.
+
+CSRF is entirely a browser based attack. Some background knowledge of how browsers work enables us to provide a filter that will prevent CSRF attacks. HTTP requests from a web browser performed via form, image, iframe, etc are unable to set custom HTTP headers. The only way to create a HTTP request from a browser with a custom HTTP header is to use a technology such as Javascript XMLHttpRequest or Flash. These technologies can set custom HTTP headers, but have security policies built in to prevent web sites from sending requests to each other
+unless specifically allowed by policy.
+
+This means that a website www.bad.com cannot send a request to http://bank.example.com with the custom header X-XSRF-Header unless they use a technology such as a XMLHttpRequest. That technology would prevent such a request from being made unless the bank.example.com domain specifically allowed it. This then results in a REST endpoint that can only be called via XMLHttpRequest (or similar technology).
+
+NOTE: by enabling this protection within the topology, this custom header will be required for *all* clients that interact with it - not just browsers.
+
+#### CORS
+For security reasons, browsers restrict cross-origin HTTP requests initiated from within scripts. For example, XMLHttpRequest follows the same-origin policy. So, a web application using XMLHttpRequest could only make HTTP requests to its own domain. To improve web applications, developers asked browser vendors to allow XMLHttpRequest to make cross-domain requests.
+
+Cross Origin Resource Sharing is a way to explicitly alter the same-origin policy for a given application or API. In order to allow for applications to make cross domain requests through Apache Knox, we need to configure the CORS filter of the WebAppSec provider.
+
+
+#### Configuration ####
+##### Overview #####
+As with all providers in the Knox gateway, the web app security provider is configured through provider params. Unlike many other providers, the web app security provider may actually host multiple vulnerability/security filters. Currently, we only have implementations for CSRF and CORS but others will follow and you may be interested in creating your own.
+
+Because of this one-to-many provider/filter relationship, there is an extra configuration element for this provider per filter. As you can see in the sample below, the actual filter configuration is defined entirely within the params of the WebAppSec provider.
+
+ <provider>
+ <role>webappsec</role>
+ <name>WebAppSec</name>
+ <enabled>true</enabled>
+ <param><name>csrf.enabled</name><value>true</value></param>
+ <param><name>csrf.customHeader</name><value>X-XSRF-Header</value></param>
+ <param><name>csrf.methodsToIgnore</name><value>GET,OPTIONS,HEAD</value></param>
+ <param><name>cors.enabled</name><value>true</value></param>
+ <param><name>xframe-options.enabled</name><value>true</value></param>
+ </provider>
+
+#### Descriptions ####
+The following tables describes the configuration options for the web app security provider:
+
+##### CSRF
+
+###### Config
+
+Name | Description | Default
+---------|-----------
+csrf.enabled|This param enables the CSRF protection capabilities|false
+csrf.customHeader|This is an optional param that indicates the name of the header to be used in order to determine that the request is from a trusted source. It defaults to the header name described by the NSA in its guidelines for dealing with CSRF in REST.|X-XSRF-Header
+csrf.methodsToIgnore|This is also an optional param that enumerates the HTTP methods to allow through without the custom HTTP header. This is useful for allowing things like GET requests from the URL bar of a browser but it assumes that the GET request adheres to REST principals in terms of being idempotent. If this cannot be assumed then it would be wise to not include GET in the list of methods to ignore.|GET,OPTIONS,HEAD
+
+###### REST Invocation
+The following curl command can be used to request a directory listing from HDFS while passing in the expected header X-XSRF-Header.
+
+ curl -k -i --header "X-XSRF-Header: valid" -v -u guest:guest-password https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS
+
+Omitting the --header "X-XSRF-Header: valid" above should result in an HTTP 400 bad_request.
+
+Disabling the provider will then allow a request that is missing the header through.
+
+##### CORS
+
+###### Config
+
+Name | Description | Default
+-----------------------------|-------------|---------
+cors.enabled | This param enables the CORS capabilities|false
+cors.allowGenericHttpRequests| {true\|false} defaults to true. If true generic HTTP requests will be allowed to pass through the filter, else only valid and accepted CORS requests will be allowed (strict CORS filtering).|true
+cors.allowOrigin | {"\*"\|origin-list} defaults to "\*". Whitespace-separated list of origins that the CORS filter must allow. Requests from origins not included here will be refused with an HTTP 403 "Forbidden" response. If set to \* (asterisk) any origin will be allowed.|"\*"
+cors.allowSubdomains | {true\|false} defaults to false. If true the CORS filter will allow requests from any origin which is a subdomain origin of the allowed origins. A subdomain is matched by comparing its scheme and suffix (host name / IP address and optional port number).|false
+cors.supportedMethods | {method-list} defaults to GET, POST, HEAD, OPTIONS. List of the supported HTTP methods. These are advertised through the Access-Control-Allow-Methods header and must also be implemented by the actual CORS web service. Requests for methods not included here will be refused by the CORS filter with an HTTP 405 "Method not allowed" response.| GET, POST, HEAD, OPTIONS
+cors.supportedHeaders | {"\*"\|header-list} defaults to \*. The names of the supported author request headers. These are advertised through the Access-Control-Allow-Headers header. If the configuration property value is set to \* (asterisk) any author request header will be allowed. The CORS Filter implements this by simply echoing the requested value back to the browser.|\*
+cors.exposedHeaders | {header-list} defaults to empty list. List of the response headers other than simple response headers that the browser should expose to the author of the cross-domain request through the XMLHttpRequest.getResponseHeader() method. The CORS filter supplies this information through the Access-Control-Expose-Headers header.| empty
+cors.supportsCredentials | {true\|false} defaults to true. Indicates whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported. The CORS filter uses this value in constructing the Access-Control-Allow-Credentials header.|true
+cors.maxAge | {int} defaults to -1 (unspecified). Indicates how long the results of a preflight request can be cached by the web browser, in seconds. If -1 unspecified. This information is passed to the browser via the Access-Control-Max-Age header.| -1
+cors.tagRequests | {true\|false} defaults to false (no tagging). Enables HTTP servlet request tagging to provide CORS information to downstream handlers (filters and/or servlets).| false
+
+##### X-Frame-Options
+
+Cross Frame Scripting and Clickjacking are attackes that can be prevented by controlling the ability for a third-party to embed an application or resource within a Frame, IFrame or Object html element. This can be done adding the X-Frame-Options HTTP header to responses.
+
+###### Config
+
+Name | Description | Default
+-----------------------------|-------------|---------
+xframe-options.enabled | This param enables the X-Frame-Options capabilities|false
+xframe-options.value | This param specifies a particular value for the X-Frame-Options header. Most often the default value of DENY will be most appropriate. You can also use SAMEORIGIN or ALLOW-FROM uri|DENY
+