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.
+
+
