knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lmc...@apache.org
Subject svn commit: r1774044 [4/7] - in /knox/trunk/books/0.11.0: ./ dev-guide/
Date Tue, 13 Dec 2016 16:00:36 GMT
Added: knox/trunk/books/0.11.0/config_pac4j_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/config_pac4j_provider.md?rev=1774044&view=auto
==============================================================================
--- knox/trunk/books/0.11.0/config_pac4j_provider.md (added)
+++ knox/trunk/books/0.11.0/config_pac4j_provider.md Tue Dec 13 16:00:35 2016
@@ -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.11.0/config_pam_authn.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/config_pam_authn.md?rev=1774044&view=auto
==============================================================================
--- knox/trunk/books/0.11.0/config_pam_authn.md (added)
+++ knox/trunk/books/0.11.0/config_pam_authn.md Tue Dec 13 16:00:35 2016
@@ -0,0 +1,82 @@
+<!---
+   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.11.0/config_preauth_sso_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/config_preauth_sso_provider.md?rev=1774044&view=auto
==============================================================================
--- knox/trunk/books/0.11.0/config_preauth_sso_provider.md (added)
+++ knox/trunk/books/0.11.0/config_preauth_sso_provider.md Tue Dec 13 16:00:35 2016
@@ -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.11.0/config_sandbox.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/config_sandbox.md?rev=1774044&view=auto
==============================================================================
--- knox/trunk/books/0.11.0/config_sandbox.md (added)
+++ knox/trunk/books/0.11.0/config_sandbox.md Tue Dec 13 16:00:35 2016
@@ -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.11.0/config_webappsec_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/config_webappsec_provider.md?rev=1774044&view=auto
==============================================================================
--- knox/trunk/books/0.11.0/config_webappsec_provider.md (added)
+++ knox/trunk/books/0.11.0/config_webappsec_provider.md Tue Dec 13 16:00:35 2016
@@ -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
+



Mime
View raw message