You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by lm...@apache.org on 2015/11/29 18:51:23 UTC
svn commit: r1717101 - in /knox: site/ site/books/knox-0-7-0/
trunk/books/0.7.0/
Author: lmccay
Date: Sun Nov 29 17:51:22 2015
New Revision: 1717101
URL: http://svn.apache.org/viewvc?rev=1717101&view=rev
Log:
added knox_sso_config
Added:
knox/trunk/books/0.7.0/config_knox_sso.md
Modified:
knox/site/books/knox-0-7-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.7.0/book.md
knox/trunk/books/0.7.0/book_gateway-details.md
Modified: knox/site/books/knox-0-7-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-7-0/user-guide.html?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/site/books/knox-0-7-0/user-guide.html (original)
+++ knox/site/books/knox-0-7-0/user-guide.html Sun Nov 29 17:51:22 2015
@@ -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" alt="Apache"/> --> <img src="apache-logo.gif" align="right" alt="Apache"/></p><h1><a id="Apache+Knox+Gateway+0.6.x+User's+Guide">Apache Knox Gateway 0.6.x User’s Guide</a> <a href="#Apache+Knox+Gateway+0.6.x+User'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" alt="Apache"/> --> <img src="apache-logo.gif" align="right" alt="Apache"/></p><h1><a id="Apache+Knox+Gateway+0.7.x+User's+Guide">Apache Knox Gateway 0.7.x User’s Guide</a> <a href="#Apache+Knox+Gateway+0.7.x+User'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="#Introduction">Introduction</a></li>
<li><a href="#Quick+Start">Quick Start</a></li>
@@ -40,6 +40,7 @@
<li><a href="#High+Availability">High Availability</a></li>
<li><a href="#Web+App+Security+Provider">Web App Security Provider</a></li>
<li><a href="#Preauthenticated+SSO+Provider">Preauthenticated SSO Provider</a></li>
+ <li><a href="#KnoxSSO+Setup+and+Configuration">KnoxSSO Setup and Configuration</a></li>
<li><a href="#Audit">Audit</a></li>
</ul></li>
<li><a href="#Client+Details">Client Details</a></li>
@@ -2022,7 +2023,135 @@ APACHE_HOME/bin/apachectl -k stop
</provider>
</code></pre><h5><a id="REST+Invocation+for+Tivoli+AM">REST Invocation for Tivoli AM</a> <a href="#REST+Invocation+for+Tivoli+AM"><img src="markbook-section-link.png"/></a></h5><p>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.</p>
<pre><code>curl -k -i --header "iv_user: guest" --header "iv_group: admin" -v https://localhost:8443/gateway/sandbox/webhdfs/v1/tmp?op=LISTSTATUS
-</code></pre><p>Omitting the –header “iv_user: guest” above will result in a rejected request.</p><h3><a id="Mutual+Authentication+with+SSL">Mutual Authentication with SSL</a> <a href="#Mutual+Authentication+with+SSL"><img src="markbook-section-link.png"/></a></h3><p>To establish a stronger trust relationship between client and server, we provide mutual authentication with SSL via client certs. This is particularly useful in providing additional validation for Preauthenticated SSO with HTTP Headers. Rather than just ip address validation, connections will only be accepted by Knox from clients presenting trusted certificates.</p><p>This behavior is configured for the entire gateway instance within the gateway-site.xml file. All topologies deployed within the gateway instance with mutual authentication enabled will require incoming connections to present trusted client certificates during the SSL handshake. Otherwise, connections will be refused.</p><p>The following
table describes the configuration elements related to mutual authentication and their defaults:</p>
+</code></pre><p>Omitting the –header “iv_user: guest” above will result in a rejected request.</p><h1><a id="KnoxSSO+Setup+and+Configuration">KnoxSSO Setup and Configuration</a> <a href="#KnoxSSO+Setup+and+Configuration"><img src="markbook-section-link.png"/></a></h1><h2><a id="Introduction">Introduction</a> <a href="#Introduction"><img src="markbook-section-link.png"/></a></h2>
+<hr/><p>Authentication of the Hadoop component UIs, and those of the overall ecosystem, is usually limited to Kerberos (which requires SPNEGO to be configured for the user’s browser) and simple/psuedo. This often results in the UIs not being secured - even in secured clusters. This is where KnoxSSO provides value for through providing WebSSO capabilities to the Hadoop cluster.</p><p>By leveraging the hadoop-auth module in Hadoop common, we have introduced the ability to consume a common SSO cookie for web UIs while retaining the non-web browser authentication through kerberos/SPNEGO. We do this by extneding the AltKerberosAuthenticationHandler class which provides the useragent based multiplexing. </p><p>We also provide integration guidance within the developers guide for other applications to be able to participate in these SSO capabilities.</p><p>The flexibility of the Apache Knox authentication and federation providers allows KnoxSSO to provide a normalization of authentica
tion events through token exchange resulting in a common JWT (JSON WebToken) based token.</p><p>KnoxSSO provides an abstraction for integrating any number of authentication systems and SSO solutions and enables participating web applications to scale to those solutions more easily. Without the token exchange capabilities offered by KnoxSSO each component UI would need to integrate with each desired solution on its own. With KnoxSSO they only need to integrate with the single solution and common token.</p><p>This document describes the overall setup requirements for KnoxSSO and participating applications. [Please see the integration guide for instructions in adding support for new applications.]</p><h4><a id="KnoxSSO+Setup">KnoxSSO Setup</a> <a href="#KnoxSSO+Setup"><img src="markbook-section-link.png"/></a></h4><h5><a id="knoxsso.xml+Topology">knoxsso.xml Topology</a> <a href="#knoxsso.xml+Topology"><img src="markbook-section-link.png"/></a></h5><p>To enable KnoxSSO, we need to conf
igure the KnoxSSO topology. The following is an example of this topology which is configured to use HTTP Basic Auth against the Knox Demo LDAP server. This is the lowest barrier of entry for your development environment that actually authenticates against a real user store. Whatâs great is if you work against the IdP with Basic Auth then you will work with SAML or anything else as well. SAML support is provided through our PicketLink federation provider and we will provide an example configuration for that as well.</p>
+<pre><code> <?xml version="1.0" encoding="utf-8"?>
+ <topology>
+ <gateway>
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapContextFactory</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory</name>
+ <value>$ldapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</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*$</value>
+ </param>
+ </service>
+ </topology>
+</code></pre><p>Just as with any Knox service, the KNOXSSO service is protected by the gateway providers defined above it. In this case, the ShiroProvider is taking care of HTTP Basic Auth against LDAP for us. Once the user authenticates the request processing continues to the KNOXSSO service that will create the required cookie and do the necessary redirects.</p><p>The authentication/federation provider can be swapped out to fit your deployment environment.</p><p>This is a good place to start in the setup of KnoxSSO as it doesn’t pull in dependencies on external identity solutions. Once we have this working, we can switch to a federation provider and integrate a preferred SSO solution.</p><p>This topology will result in a KnoxSSO URL that looks something like:</p>
+<pre><code>https://{gateway_host}:{gateway_port}/gateway/knoxsso/api/v1/websso
+</code></pre><p>This URL is needed when configuring applications that participate in KnoxSSO for a given deployment. We will refer to this as the Provider URL in this document.</p><h3><a id="KnoxSSO+Configuration+Parameters">KnoxSSO Configuration Parameters</a> <a href="#KnoxSSO+Configuration+Parameters"><img src="markbook-section-link.png"/></a></h3>
+<table>
+ <thead>
+ <tr>
+ <th>Parameter </th>
+ <th>Description </th>
+ <th>Default</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>knoxsso.cookie.secure.only </td>
+ <td>This determines whether the browser is allowed to send the cookie over unsecured channels. This should always be set to true in production systems. If during development a relying party is not running ssl then you can turn this off. Running with it off exposes the cookie and underlying token for capture and replay by others. </td>
+ <td>true</td>
+ </tr>
+ <tr>
+ <td>knoxsso.cookie.max.age </td>
+ <td>optional: This indicates that a cookie can only live for a specified amount of time - in seconds. This should probably be left to the default which makes it a session cookie. Session cookies are discarded once the browser session is closed. </td>
+ <td>session</td>
+ </tr>
+ <tr>
+ <td>knoxsso.token.ttl </td>
+ <td>This indicates the lifespan of the token within the cookie. Once it expires a new cookie must be acquired from KnoxSSO. This is in milliseconds. The 36000000 in the topology above gives you 10 hrs. </td>
+ <td>30000 That is 30 seconds.</td>
+ </tr>
+ <tr>
+ <td>knoxsso.token.audiences </td>
+ <td>This is a comma separated list of audiences to add to the JWT token. This is used to ensure that a token received by a participating application knows that the token was intended for use with that application. It is optional. In the event that an application has expected audiences and they are not present the token must be rejected. In the event where the token has audiences and the application has none expected then the token is accepted. OPEN ISSUE - not currently being populated in WebSSOResource. </td>
+ <td>empty</td>
+ </tr>
+ <tr>
+ <td>knoxsso.redirect.whitelist.regex </td>
+ <td>A semicolon separated list of regex expressions. The incoming originalUrl must match one of the expressions in order for KnoxSSO to redirect to it after authentication. Defaults to only relative paths and localhost with or without SSL for development usecases. This needs to be opened up for production use and actual participating applications. Note that cookie use is still constrained to redirect destinations in the same domain as the KnoxSSO service - regardless of the expressions specified here. </td>
+ <td>^/.*$;^https?://localhost:\d{0,9}/.*$</td>
+ </tr>
+ </tbody>
+</table><h3><a id="Hadoop+Configuration+Example">Hadoop Configuration Example</a> <a href="#Hadoop+Configuration+Example"><img src="markbook-section-link.png"/></a></h3><p>The following is used as the KnoxSSO configuration in the Hadoop JWTRedirectAuthenticationHandler implementation. Any participating application will need similar configuration. Since JWTRedirectAuthenticationHandler extends the AltKerberosAuthenticationHandler, the typical kerberos configuration parameters for authentication are also required.</p>
+<pre><code> <property>
+ <name>hadoop.http.authentication.type</name> <value>org.apache.hadoop.security.authentication.server.JWTRedirectAuthenticationHandler</value>
+ </property>
+</code></pre><p>This is the handler classname in Hadoop auth for JWT token (KnoxSSO) support.</p>
+<pre><code> <property>
+ <name>hadoop.http.authentication.authentication.provider.url</name>
+ <value>http://c6401.ambari.apache.org:8888/knoxsso</value>
+ </property>
+</code></pre><p>The above property is the SSO provider URL that points to the knoxsso endpoint.</p>
+<pre><code> <property>
+ <name>hadoop.http.authentication.public.key.pem</name>
+ <value>MIICVjCCAb+gAwIBAgIJAPPvOtuTxFeiMA0GCSqGSIb3DQEBBQUAMG0xCzAJBgNV
+ BAYTAlVTMQ0wCwYDVQQIEwRUZXN0MQ0wCwYDVQQHEwRUZXN0MQ8wDQYDVQQKEwZI
+ YWRvb3AxDTALBgNVBAsTBFRlc3QxIDAeBgNVBAMTF2M2NDAxLmFtYmFyaS5hcGFj
+ aGUub3JnMB4XDTE1MDcxNjE4NDcyM1oXDTE2MDcxNTE4NDcyM1owbTELMAkGA1UE
+ BhMCVVMxDTALBgNVBAgTBFRlc3QxDTALBgNVBAcTBFRlc3QxDzANBgNVBAoTBkhh
+ ZG9vcDENMAsGA1UECxMEVGVzdDEgMB4GA1UEAxMXYzY0MDEuYW1iYXJpLmFwYWNo
+ ZS5vcmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMFs/rymbiNvg8lDhsdA
+ qvh5uHP6iMtfv9IYpDleShjkS1C+IqId6bwGIEO8yhIS5BnfUR/fcnHi2ZNrXX7x
+ QUtQe7M9tDIKu48w//InnZ6VpAqjGShWxcSzR6UB/YoGe5ytHS6MrXaormfBg3VW
+ tDoy2MS83W8pweS6p5JnK7S5AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEANyVg6EzE
+ 2q84gq7wQfLt9t047nYFkxcRfzhNVL3LB8p6IkM4RUrzWq4kLA+z+bpY2OdpkTOe
+ wUpEdVKzOQd4V7vRxpdANxtbG/XXrJAAcY/S+eMy1eDK73cmaVPnxPUGWmMnQXUi
+ TLab+w8tBQhNbq6BOQ42aOrLxA8k/M4cV1A=</value>
+ </property>
+</code></pre><p>The above property holds the KnoxSSO serverâs public key for signature verification. Adding it directly to the config like this is convenient and is easily done through Ambari to existing config files that take custom properties. Config is generally protected as root access only as well - so it is a pretty good solution.</p><h3><a id="Mutual+Authentication+with+SSL">Mutual Authentication with SSL</a> <a href="#Mutual+Authentication+with+SSL"><img src="markbook-section-link.png"/></a></h3><p>To establish a stronger trust relationship between client and server, we provide mutual authentication with SSL via client certs. This is particularly useful in providing additional validation for Preauthenticated SSO with HTTP Headers. Rather than just ip address validation, connections will only be accepted by Knox from clients presenting trusted certificates.</p><p>This behavior is configured for the entire gateway instance within the gateway-site.xml file. All topologies
deployed within the gateway instance with mutual authentication enabled will require incoming connections to present trusted client certificates during the SSL handshake. Otherwise, connections will be refused.</p><p>The following table describes the configuration elements related to mutual authentication and their defaults:</p>
<table>
<thead>
<tr>
Modified: knox/site/index.html
URL: http://svn.apache.org/viewvc/knox/site/index.html?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Sun Nov 29 17:51:22 2015
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2015-11-27
+ | Generated by Apache Maven Doxia at 2015-11-29
| 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="20151127" />
+ <meta name="Date-Revision-yyyymmdd" content="20151129" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – REST API Gateway for the 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: 2015-11-27</li>
+ <li id="publishDate" class="pull-right">Last Published: 2015-11-29</li>
</ul>
</div>
Modified: knox/site/issue-tracking.html
URL: http://svn.apache.org/viewvc/knox/site/issue-tracking.html?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/site/issue-tracking.html (original)
+++ knox/site/issue-tracking.html Sun Nov 29 17:51:22 2015
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2015-11-27
+ | Generated by Apache Maven Doxia at 2015-11-29
| 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="20151127" />
+ <meta name="Date-Revision-yyyymmdd" content="20151129" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – 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: 2015-11-27</li>
+ <li id="publishDate" class="pull-right">Last Published: 2015-11-29</li>
</ul>
</div>
Modified: knox/site/license.html
URL: http://svn.apache.org/viewvc/knox/site/license.html?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/site/license.html (original)
+++ knox/site/license.html Sun Nov 29 17:51:22 2015
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2015-11-27
+ | Generated by Apache Maven Doxia at 2015-11-29
| 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="20151127" />
+ <meta name="Date-Revision-yyyymmdd" content="20151129" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – 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: 2015-11-27</li>
+ <li id="publishDate" class="pull-right">Last Published: 2015-11-29</li>
</ul>
</div>
Modified: knox/site/mail-lists.html
URL: http://svn.apache.org/viewvc/knox/site/mail-lists.html?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/site/mail-lists.html (original)
+++ knox/site/mail-lists.html Sun Nov 29 17:51:22 2015
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2015-11-27
+ | Generated by Apache Maven Doxia at 2015-11-29
| 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="20151127" />
+ <meta name="Date-Revision-yyyymmdd" content="20151129" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – 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: 2015-11-27</li>
+ <li id="publishDate" class="pull-right">Last Published: 2015-11-29</li>
</ul>
</div>
Modified: knox/site/project-info.html
URL: http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Sun Nov 29 17:51:22 2015
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2015-11-27
+ | Generated by Apache Maven Doxia at 2015-11-29
| 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="20151127" />
+ <meta name="Date-Revision-yyyymmdd" content="20151129" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – 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: 2015-11-27</li>
+ <li id="publishDate" class="pull-right">Last Published: 2015-11-29</li>
</ul>
</div>
Modified: knox/site/team-list.html
URL: http://svn.apache.org/viewvc/knox/site/team-list.html?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/site/team-list.html (original)
+++ knox/site/team-list.html Sun Nov 29 17:51:22 2015
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2015-11-27
+ | Generated by Apache Maven Doxia at 2015-11-29
| 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="20151127" />
+ <meta name="Date-Revision-yyyymmdd" content="20151129" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – 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: 2015-11-27</li>
+ <li id="publishDate" class="pull-right">Last Published: 2015-11-29</li>
</ul>
</div>
Modified: knox/trunk/books/0.7.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.7.0/book.md?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/trunk/books/0.7.0/book.md (original)
+++ knox/trunk/books/0.7.0/book.md Sun Nov 29 17:51:22 2015
@@ -21,7 +21,7 @@
<!-- <img src="apache-logo.gif" alt="Apache"/> -->
<img src="apache-logo.gif" align="right" alt="Apache"/>
-# Apache Knox Gateway 0.6.x User's Guide #
+# Apache Knox Gateway 0.7.x User's Guide #
## Table Of Contents ##
@@ -47,6 +47,7 @@
* #[High Availability]
* #[Web App Security Provider]
* #[Preauthenticated SSO Provider]
+ * #[KnoxSSO Setup and Configuration]
* #[Audit]
* #[Client Details]
* #[Service Details]
Modified: knox/trunk/books/0.7.0/book_gateway-details.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.7.0/book_gateway-details.md?rev=1717101&r1=1717100&r2=1717101&view=diff
==============================================================================
--- knox/trunk/books/0.7.0/book_gateway-details.md (original)
+++ knox/trunk/books/0.7.0/book_gateway-details.md Sun Nov 29 17:51:22 2015
@@ -89,5 +89,6 @@ Their values can also be provided via th
<<config_ha.md>>
<<config_webappsec_provider.md>>
<<config_preauth_sso_provider.md>>
+<<config_knox_sso.md>>
<<config_mutual_authentication_ssl.md>>
<<config_audit.md>>
Added: knox/trunk/books/0.7.0/config_knox_sso.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.7.0/config_knox_sso.md?rev=1717101&view=auto
==============================================================================
--- knox/trunk/books/0.7.0/config_knox_sso.md (added)
+++ knox/trunk/books/0.7.0/config_knox_sso.md Sun Nov 29 17:51:22 2015
@@ -0,0 +1,153 @@
+# KnoxSSO Setup and Configuration
+
+## Introduction
+---
+
+Authentication of the Hadoop component UIs, and those of the overall ecosystem, is usually limited to Kerberos (which requires SPNEGO to be configured for the user's browser) and simple/psuedo. This often results in the UIs not being secured - even in secured clusters. This is where KnoxSSO provides value for through providing WebSSO capabilities to the Hadoop cluster.
+
+By leveraging the hadoop-auth module in Hadoop common, we have introduced the ability to consume a common SSO cookie for web UIs while retaining the non-web browser authentication through kerberos/SPNEGO. We do this by extneding the AltKerberosAuthenticationHandler class which provides the useragent based multiplexing.
+
+We also provide integration guidance within the developers guide for other applications to be able to participate in these SSO capabilities.
+
+The flexibility of the Apache Knox authentication and federation providers allows KnoxSSO to provide a normalization of authentication events through token exchange resulting in a common JWT (JSON WebToken) based token.
+
+KnoxSSO provides an abstraction for integrating any number of authentication systems and SSO solutions and enables participating web applications to scale to those solutions more easily. Without the token exchange capabilities offered by KnoxSSO each component UI would need to integrate with each desired solution on its own. With KnoxSSO they only need to integrate with the single solution and common token.
+
+This document describes the overall setup requirements for KnoxSSO and participating applications. [Please see the integration guide for instructions in adding support for new applications.]
+
+## KnoxSSO Setup
+
+### knoxsso.xml Topology
+To enable KnoxSSO, we need to configure the KnoxSSO topology. The following is an example of this topology which is configured to use HTTP Basic Auth against the Knox Demo LDAP server. This is the lowest barrier of entry for your development environment that actually authenticates against a real user store. Whatâs great is if you work against the IdP with Basic Auth then you will work with SAML or anything else as well. SAML support is provided through our PicketLink federation provider and we will provide an example configuration for that as well.
+
+```
+ <?xml version="1.0" encoding="utf-8"?>
+ <topology>
+ <gateway>
+ <provider>
+ <role>authentication</role>
+ <name>ShiroProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sessionTimeout</name>
+ <value>30</value>
+ </param>
+ <param>
+ <name>main.ldapRealm</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapRealm</value>
+ </param>
+ <param>
+ <name>main.ldapContextFactory</name>
+ <value>org.apache.hadoop.gateway.shirorealm.KnoxLdapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory</name>
+ <value>$ldapContextFactory</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.userDnTemplate</name>
+ <value>uid={0},ou=people,dc=hadoop,dc=apache,dc=org</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.url</name>
+ <value>ldap://localhost:33389</value>
+ </param>
+ <param>
+ <name>main.ldapRealm.contextFactory.authenticationMechanism</name>
+ <value>simple</value>
+ </param>
+ <param>
+ <name>urls./**</name>
+ <value>authcBasic</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*$</value>
+ </param>
+ </service>
+ </topology>
+```
+
+Just as with any Knox service, the KNOXSSO service is protected by the gateway providers defined above it. In this case, the ShiroProvider is taking care of HTTP Basic Auth against LDAP for us. Once the user authenticates the request processing continues to the KNOXSSO service that will create the required cookie and do the necessary redirects.
+
+The authentication/federation provider can be swapped out to fit your deployment environment.
+
+This is a good place to start in the setup of KnoxSSO as it doesn't pull in dependencies on external identity solutions. Once we have this working, we can switch to a federation provider and integrate a preferred SSO solution.
+
+This topology will result in a KnoxSSO URL that looks something like:
+
+ https://{gateway_host}:{gateway_port}/gateway/knoxsso/api/v1/websso
+
+This URL is needed when configuring applications that participate in KnoxSSO for a given deployment. We will refer to this as the Provider URL in this document.
+
+### KnoxSSO Configuration Parameters
+
+Parameter | Description | Default
+--------- |----------- |-----------
+knoxsso.cookie.secure.only | This determines whether the browser is allowed to send the cookie over unsecured channels. This should always be set to true in production systems. If during development a relying party is not running ssl then you can turn this off. Running with it off exposes the cookie and underlying token for capture and replay by others. | true
+knoxsso.cookie.max.age | optional: This indicates that a cookie can only live for a specified amount of time - in seconds. This should probably be left to the default which makes it a session cookie. Session cookies are discarded once the browser session is closed. | session
+knoxsso.token.ttl | This indicates the lifespan of the token within the cookie. Once it expires a new cookie must be acquired from KnoxSSO. This is in milliseconds. The 36000000 in the topology above gives you 10 hrs. | 30000 That is 30 seconds.
+knoxsso.token.audiences | This is a comma separated list of audiences to add to the JWT token. This is used to ensure that a token received by a participating application knows that the token was intended for use with that application. It is optional. In the event that an application has expected audiences and they are not present the token must be rejected. In the event where the token has audiences and the application has none expected then the token is accepted. OPEN ISSUE - not currently being populated in WebSSOResource. | empty
+knoxsso.redirect.whitelist.regex | A semicolon separated list of regex expressions. The incoming originalUrl must match one of the expressions in order for KnoxSSO to redirect to it after authentication. Defaults to only relative paths and localhost with or without SSL for development usecases. This needs to be opened up for production use and actual participating applications. Note that cookie use is still constrained to redirect destinations in the same domain as the KnoxSSO service - regardless of the expressions specified here. | ^/.\*$;^https?://localhost:\\d{0,9}/.\*$
+
+
+## Participating Application Configuration
+### Hadoop Configuration Example
+The following is used as the KnoxSSO configuration in the Hadoop JWTRedirectAuthenticationHandler implementation. Any participating application will need similar configuration. Since JWTRedirectAuthenticationHandler extends the AltKerberosAuthenticationHandler, the typical kerberos configuration parameters for authentication are also required.
+
+```
+ <property>
+ <name>hadoop.http.authentication.type</name> <value>org.apache.hadoop.security.authentication.server.JWTRedirectAuthenticationHandler</value>
+ </property>
+```
+
+This is the handler classname in Hadoop auth for JWT token (KnoxSSO) support.
+
+```
+ <property>
+ <name>hadoop.http.authentication.authentication.provider.url</name>
+ <value>http://c6401.ambari.apache.org:8888/knoxsso</value>
+ </property>
+```
+
+The above property is the SSO provider URL that points to the knoxsso endpoint.
+
+```
+ <property>
+ <name>hadoop.http.authentication.public.key.pem</name>
+ <value>MIICVjCCAb+gAwIBAgIJAPPvOtuTxFeiMA0GCSqGSIb3DQEBBQUAMG0xCzAJBgNV
+ BAYTAlVTMQ0wCwYDVQQIEwRUZXN0MQ0wCwYDVQQHEwRUZXN0MQ8wDQYDVQQKEwZI
+ YWRvb3AxDTALBgNVBAsTBFRlc3QxIDAeBgNVBAMTF2M2NDAxLmFtYmFyaS5hcGFj
+ aGUub3JnMB4XDTE1MDcxNjE4NDcyM1oXDTE2MDcxNTE4NDcyM1owbTELMAkGA1UE
+ BhMCVVMxDTALBgNVBAgTBFRlc3QxDTALBgNVBAcTBFRlc3QxDzANBgNVBAoTBkhh
+ ZG9vcDENMAsGA1UECxMEVGVzdDEgMB4GA1UEAxMXYzY0MDEuYW1iYXJpLmFwYWNo
+ ZS5vcmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMFs/rymbiNvg8lDhsdA
+ qvh5uHP6iMtfv9IYpDleShjkS1C+IqId6bwGIEO8yhIS5BnfUR/fcnHi2ZNrXX7x
+ QUtQe7M9tDIKu48w//InnZ6VpAqjGShWxcSzR6UB/YoGe5ytHS6MrXaormfBg3VW
+ tDoy2MS83W8pweS6p5JnK7S5AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEANyVg6EzE
+ 2q84gq7wQfLt9t047nYFkxcRfzhNVL3LB8p6IkM4RUrzWq4kLA+z+bpY2OdpkTOe
+ wUpEdVKzOQd4V7vRxpdANxtbG/XXrJAAcY/S+eMy1eDK73cmaVPnxPUGWmMnQXUi
+ TLab+w8tBQhNbq6BOQ42aOrLxA8k/M4cV1A=</value>
+ </property>
+```
+
+The above property holds the KnoxSSO serverâs public key for signature verification. Adding it directly to the config like this is convenient and is easily done through Ambari to existing config files that take custom properties. Config is generally protected as root access only as well - so it is a pretty good solution.
+
+