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 2017/02/24 20:39:11 UTC
svn commit: r1784323 - in /knox: site/books/knox-0-11-0/
site/books/knox-0-12-0/ trunk/books/0.11.0/ trunk/books/0.12.0/
trunk/books/0.12.0/dev-guide/
Author: lmccay
Date: Fri Feb 24 20:39:11 2017
New Revision: 1784323
URL: http://svn.apache.org/viewvc?rev=1784323&view=rev
Log:
added SSOCookieProvider docs
Added:
knox/trunk/books/0.11.0/config_sso_cookie_provider.md
knox/trunk/books/0.12.0/config_sso_cookie_provider.md
Modified:
knox/site/books/knox-0-11-0/user-guide.html
knox/site/books/knox-0-12-0/dev-guide.html
knox/site/books/knox-0-12-0/knoxsso_integration.html
knox/site/books/knox-0-12-0/user-guide.html
knox/trunk/books/0.11.0/book.md
knox/trunk/books/0.11.0/book_gateway-details.md
knox/trunk/books/0.12.0/book.md
knox/trunk/books/0.12.0/book_gateway-details.md
knox/trunk/books/0.12.0/dev-guide/knoxsso_integration.md
Modified: knox/site/books/knox-0-11-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-11-0/user-guide.html?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/site/books/knox-0-11-0/user-guide.html (original)
+++ knox/site/books/knox-0-11-0/user-guide.html Fri Feb 24 20:39:11 2017
@@ -40,6 +40,7 @@
<li><a href="#LDAP+Group+Lookup">LDAP Group Lookup</a></li>
<li><a href="#PAM+based+Authentication">PAM based Authentication</a></li>
<li><a href="#HadoopAuth+Authentication+Provider">HadoopAuth Authentication Provider</a></li>
+ <li><a href="#SSO+Cookie+Provider">SSO Cookie Provider</a></li>
<li><a href="#Preauthenticated+SSO+Provider">Preauthenticated SSO Provider</a></li>
<li><a href="#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect">Pac4j Provider - CAS / OAuth / SAML / OpenID Connect</a></li>
<li><a href="#KnoxSSO+Setup+and+Configuration">KnoxSSO Setup and Configuration</a></li>
@@ -2476,7 +2477,58 @@ 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="Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect">Pac4j Provider - CAS / OAuth / SAML / OpenID Connect</a> <a href="#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect"><img src="markbook-section-link.png"/></a></h3>
+</code></pre><p>Omitting the –header “iv_user: guest” above will result in a rejected request.</p><h3><a id="SSO+Cookie+Provider">SSO Cookie Provider</a> <a href="#SSO+Cookie+Provider"><img src="markbook-section-link.png"/></a></h3><h4><a id="Overview">Overview</a> <a href="#Overview"><img src="markbook-section-link.png"/></a></h4><p>The SSOCookieProvider enables the federation of the authentication event that occurred through KnoxSSO. KnoxSSO is a typical SP initiated websso mechanism that sets a cookie to be presented by browsers to participating applications and cryptographically verified.</p><p>Knox Gateway needs a pluggable mechanism for consuming these cookies and federating the KnoxSSO authentication event as an asserted identity in its interaction with the Hadoop cluster for REST API invocations. This provider is useful when an application that is integrated with KnoxSSO for authentication also consumes REST APIs through the Knox Gateway.</p><p>Based on our
understanding of the websso flow it should behave like:</p>
+<ul>
+ <li>SSOCookieProvider checks for hadoop-jwt cookie and in its absence redirects to the configured SSO provider URL (knoxsso endpoint)</li>
+ <li>The configured Provider on the KnoxSSO endpoint challenges the user in a provider specific way (presents form, redirects to SAML IdP, etc)</li>
+ <li>The authentication provider on KnoxSSO validates the identity of the user through credentials/tokens</li>
+ <li>The WebSSO service exchanges the normalized Java Subject into a JWT token and sets it on the response as a cookie named hadoop-jwt</li>
+ <li>The WebSSO service then redirects the user agent back to the originally requested URL - the requested Knox service subsequent invocations will find the cookie in the incoming request and not need to engage the WebSSO service again until it expires.</li>
+</ul><h4><a id="Configuration">Configuration</a> <a href="#Configuration"><img src="markbook-section-link.png"/></a></h4><h5><a id="sandbox.xml+Topology+Example">sandbox.xml Topology Example</a> <a href="#sandbox.xml+Topology+Example"><img src="markbook-section-link.png"/></a></h5><p>Configuring one of the cluster topologies to use the SSOCookieProvider instead of the out of the box ShiroProvider would look something like the following:</p>
+<pre><code><?xml version="1.0" encoding="utf-8"?>
+<topology>
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://localhost:9443/gateway/idp/api/v1/websso</value>
+ </param>
+ </provider>
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ </provider>
+ </gateway>
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+</topology>
+</code></pre><p>The following table describes the configuration options for the web app security provider:</p><h5><a id="Descriptions">Descriptions</a> <a href="#Descriptions"><img src="markbook-section-link.png"/></a></h5>
+<table>
+ <thead>
+ <tr>
+ <th>Name </th>
+ <th>Description </th>
+ <th>Default</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sso.authentication.provider.url</td>
+ <td>Required parameter that indicates the location of the KnoxSSO endpoint and where to redirect the useragent when no SSO cookie is found in the incoming request.</td>
+ <td>N/A</td>
+ </tr>
+ </tbody>
+</table><h3><a id="Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect">Pac4j Provider - CAS / OAuth / SAML / OpenID Connect</a> <a href="#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect"><img src="markbook-section-link.png"/></a></h3>
<p align="center">
<img src="https://pac4j.github.io/pac4j/img/logo-knox.png" width="300" />
</p><p><a href="https://github.com/pac4j/pac4j">pac4j</a> is a Java security engine to authenticate users, get their profiles and manage their authorizations in order to secure Java web applications.</p><p>It supports many authentication mechanisms for UI and web services and is implemented by many frameworks and tools.</p><p>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.</p><h4><a id="Configuration">Configuration</a> <a href="#Configuration"><img src="markbook-section-link.png"/></a></h4><h5><a id="SSO+topology">SSO topology</a> <a href="#SSO+topology"><img src="markbook-section-link.png"/></a></h5><p>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):<
/p>
Modified: knox/site/books/knox-0-12-0/dev-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/dev-guide.html?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/dev-guide.html (original)
+++ knox/site/books/knox-0-12-0/dev-guide.html Fri Feb 24 20:39:11 2017
@@ -1032,15 +1032,13 @@ public class CaseShifterIdentityAssertio
<value>authcBasic</value>
</param>
</provider>
-
- <provider>
+ <provider>
<role>identity-assertion</role>
<name>Default</name>
<enabled>true</enabled>
</provider>
</gateway>
-
- <service>
+ <service>
<role>KNOXSSO</role>
<param>
<name>knoxsso.cookie.secure.only</name>
@@ -1054,65 +1052,56 @@ public class CaseShifterIdentityAssertio
</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 authenticate/federation provider can be swapped out to fit your deployment environment.</p><h5><a id="sandbox.xml+Topology">sandbox.xml Topology</a> <a href="#sandbox.xml+Topology"><img src="markbook-section-link.png"/></a></h5><p>In order to see the end to end story and use it as an example in your development, you can configure one of the cluster topologies to use the SSOCookieProvider instead of the out of the box ShiroProvider. The following is an example sandbox.xml topology that is configured for using KnoxSSO to protect access to the Hadoop REST APIs.</p>
<pre><code> <?xml version="1.0" encoding="utf-8"?>
- <topology>
- <gateway>
- <provider>
- <role>federation</role>
- <name>SSOCookieProvider</name>
- <enabled>true</enabled>
- <param>
- <name>sso.authentication.provider.url</name>
- <value>https://localhost:9443/gateway/idp/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>
-
- <service>
- <role>JOBTRACKER</role>
- <url>rpc://localhost:8050</url>
- </service>
-
- <service>
- <role>WEBHDFS</role>
- <url>http://localhost:50070/webhdfs</url>
- </service>
-
- <service>
- <role>WEBHCAT</role>
- <url>http://localhost:50111/templeton</url>
- </service>
-
- <service>
- <role>OOZIE</role>
- <url>http://localhost:11000/oozie</url>
- </service>
-
- <service>
- <role>WEBHBASE</role>
- <url>http://localhost:60080</url>
- </service>
-
- <service>
- <role>HIVE</role>
- <url>http://localhost:10001/cliservice</url>
- </service>
-
- <service>
- <role>RESOURCEMANAGER</role>
- <url>http://localhost:8088/ws</url>
- </service>
- </topology>
+<topology>
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://localhost:9443/gateway/idp/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>
+ <service>
+ <role>JOBTRACKER</role>
+ <url>rpc://localhost:8050</url>
+ </service>
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+ <service>
+ <role>OOZIE</role>
+ <url>http://localhost:11000/oozie</url>
+ </service>
+ <service>
+ <role>WEBHBASE</role>
+ <url>http://localhost:60080</url>
+ </service>
+ <service>
+ <role>HIVE</role>
+ <url>http://localhost:10001/cliservice</url>
+ </service>
+ <service>
+ <role>RESOURCEMANAGER</role>
+ <url>http://localhost:8088/ws</url>
+ </service>
+</topology>
</code></pre>
<ul>
<li>NOTE: Be aware that when using Chrome as your browser that cookies don’t seem to work for “localhost”. Either use a VM or like I did - use 127.0.0.1. Safari works with localhost without problems.</li>
Modified: knox/site/books/knox-0-12-0/knoxsso_integration.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/knoxsso_integration.html?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/knoxsso_integration.html (original)
+++ knox/site/books/knox-0-12-0/knoxsso_integration.html Fri Feb 24 20:39:11 2017
@@ -39,15 +39,13 @@
<value>authcBasic</value>
</param>
</provider>
-
- <provider>
+ <provider>
<role>identity-assertion</role>
<name>Default</name>
<enabled>true</enabled>
</provider>
</gateway>
-
- <service>
+ <service>
<role>KNOXSSO</role>
<param>
<name>knoxsso.cookie.secure.only</name>
@@ -61,65 +59,56 @@
</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 authenticate/federation provider can be swapped out to fit your deployment environment.</p><h5><a id="sandbox.xml+Topology">sandbox.xml Topology</a> <a href="#sandbox.xml+Topology"><img src="markbook-section-link.png"/></a></h5><p>In order to see the end to end story and use it as an example in your development, you can configure one of the cluster topologies to use the SSOCookieProvider instead of the out of the box ShiroProvider. The following is an example sandbox.xml topology that is configured for using KnoxSSO to protect access to the Hadoop REST APIs.</p>
<pre><code> <?xml version="1.0" encoding="utf-8"?>
- <topology>
- <gateway>
- <provider>
- <role>federation</role>
- <name>SSOCookieProvider</name>
- <enabled>true</enabled>
- <param>
- <name>sso.authentication.provider.url</name>
- <value>https://localhost:9443/gateway/idp/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>
-
- <service>
- <role>JOBTRACKER</role>
- <url>rpc://localhost:8050</url>
- </service>
-
- <service>
- <role>WEBHDFS</role>
- <url>http://localhost:50070/webhdfs</url>
- </service>
-
- <service>
- <role>WEBHCAT</role>
- <url>http://localhost:50111/templeton</url>
- </service>
-
- <service>
- <role>OOZIE</role>
- <url>http://localhost:11000/oozie</url>
- </service>
-
- <service>
- <role>WEBHBASE</role>
- <url>http://localhost:60080</url>
- </service>
-
- <service>
- <role>HIVE</role>
- <url>http://localhost:10001/cliservice</url>
- </service>
-
- <service>
- <role>RESOURCEMANAGER</role>
- <url>http://localhost:8088/ws</url>
- </service>
- </topology>
+<topology>
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://localhost:9443/gateway/idp/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>
+ <service>
+ <role>JOBTRACKER</role>
+ <url>rpc://localhost:8050</url>
+ </service>
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+ <service>
+ <role>OOZIE</role>
+ <url>http://localhost:11000/oozie</url>
+ </service>
+ <service>
+ <role>WEBHBASE</role>
+ <url>http://localhost:60080</url>
+ </service>
+ <service>
+ <role>HIVE</role>
+ <url>http://localhost:10001/cliservice</url>
+ </service>
+ <service>
+ <role>RESOURCEMANAGER</role>
+ <url>http://localhost:8088/ws</url>
+ </service>
+</topology>
</code></pre>
<ul>
<li>NOTE: Be aware that when using Chrome as your browser that cookies don’t seem to work for “localhost”. Either use a VM or like I did - use 127.0.0.1. Safari works with localhost without problems.</li>
Modified: knox/site/books/knox-0-12-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/user-guide.html?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/user-guide.html (original)
+++ knox/site/books/knox-0-12-0/user-guide.html Fri Feb 24 20:39:11 2017
@@ -41,6 +41,7 @@
<li><a href="#PAM+based+Authentication">PAM based Authentication</a></li>
<li><a href="#HadoopAuth+Authentication+Provider">HadoopAuth Authentication Provider</a></li>
<li><a href="#Preauthenticated+SSO+Provider">Preauthenticated SSO Provider</a></li>
+ <li><a href="#SSO+Cookie+Provider">SSO Cookie Provider</a></li>
<li><a href="#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect">Pac4j Provider - CAS / OAuth / SAML / OpenID Connect</a></li>
<li><a href="#KnoxSSO+Setup+and+Configuration">KnoxSSO Setup and Configuration</a></li>
<li><a href="#Mutual+Authentication+with+SSL">Mutual Authentication with SSL</a></li>
@@ -2476,7 +2477,58 @@ 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="Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect">Pac4j Provider - CAS / OAuth / SAML / OpenID Connect</a> <a href="#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect"><img src="markbook-section-link.png"/></a></h3>
+</code></pre><p>Omitting the –header “iv_user: guest” above will result in a rejected request.</p><h3><a id="SSO+Cookie+Provider">SSO Cookie Provider</a> <a href="#SSO+Cookie+Provider"><img src="markbook-section-link.png"/></a></h3><h4><a id="Overview">Overview</a> <a href="#Overview"><img src="markbook-section-link.png"/></a></h4><p>The SSOCookieProvider enables the federation of the authentication event that occurred through KnoxSSO. KnoxSSO is a typical SP initiated websso mechanism that sets a cookie to be presented by browsers to participating applications and cryptographically verified.</p><p>Knox Gateway needs a pluggable mechanism for consuming these cookies and federating the KnoxSSO authentication event as an asserted identity in its interaction with the Hadoop cluster for REST API invocations. This provider is useful when an application that is integrated with KnoxSSO for authentication also consumes REST APIs through the Knox Gateway.</p><p>Based on our
understanding of the websso flow it should behave like:</p>
+<ul>
+ <li>SSOCookieProvider checks for hadoop-jwt cookie and in its absence redirects to the configured SSO provider URL (knoxsso endpoint)</li>
+ <li>The configured Provider on the KnoxSSO endpoint challenges the user in a provider specific way (presents form, redirects to SAML IdP, etc)</li>
+ <li>The authentication provider on KnoxSSO validates the identity of the user through credentials/tokens</li>
+ <li>The WebSSO service exchanges the normalized Java Subject into a JWT token and sets it on the response as a cookie named hadoop-jwt</li>
+ <li>The WebSSO service then redirects the user agent back to the originally requested URL - the requested Knox service subsequent invocations will find the cookie in the incoming request and not need to engage the WebSSO service again until it expires.</li>
+</ul><h4><a id="Configuration">Configuration</a> <a href="#Configuration"><img src="markbook-section-link.png"/></a></h4><h5><a id="sandbox.xml+Topology+Example">sandbox.xml Topology Example</a> <a href="#sandbox.xml+Topology+Example"><img src="markbook-section-link.png"/></a></h5><p>Configuring one of the cluster topologies to use the SSOCookieProvider instead of the out of the box ShiroProvider would look something like the following:</p>
+<pre><code><?xml version="1.0" encoding="utf-8"?>
+<topology>
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://localhost:9443/gateway/idp/api/v1/websso</value>
+ </param>
+ </provider>
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ </provider>
+ </gateway>
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+</topology>
+</code></pre><p>The following table describes the configuration options for the web app security provider:</p><h5><a id="Descriptions">Descriptions</a> <a href="#Descriptions"><img src="markbook-section-link.png"/></a></h5>
+<table>
+ <thead>
+ <tr>
+ <th>Name </th>
+ <th>Description </th>
+ <th>Default</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>sso.authentication.provider.url</td>
+ <td>Required parameter that indicates the location of the KnoxSSO endpoint and where to redirect the useragent when no SSO cookie is found in the incoming request.</td>
+ <td>N/A</td>
+ </tr>
+ </tbody>
+</table><h3><a id="Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect">Pac4j Provider - CAS / OAuth / SAML / OpenID Connect</a> <a href="#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect"><img src="markbook-section-link.png"/></a></h3>
<p align="center">
<img src="https://pac4j.github.io/pac4j/img/logo-knox.png" width="300" />
</p><p><a href="https://github.com/pac4j/pac4j">pac4j</a> is a Java security engine to authenticate users, get their profiles and manage their authorizations in order to secure Java web applications.</p><p>It supports many authentication mechanisms for UI and web services and is implemented by many frameworks and tools.</p><p>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.</p><h4><a id="Configuration">Configuration</a> <a href="#Configuration"><img src="markbook-section-link.png"/></a></h4><h5><a id="SSO+topology">SSO topology</a> <a href="#SSO+topology"><img src="markbook-section-link.png"/></a></h5><p>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):<
/p>
Modified: knox/trunk/books/0.11.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/book.md?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/trunk/books/0.11.0/book.md (original)
+++ knox/trunk/books/0.11.0/book.md Fri Feb 24 20:39:11 2017
@@ -45,6 +45,7 @@
* #[LDAP Group Lookup]
* #[PAM based Authentication]
* #[HadoopAuth Authentication Provider]
+ * #[SSO Cookie Provider]
* #[Preauthenticated SSO Provider]
* #[Pac4j Provider - CAS / OAuth / SAML / OpenID Connect]
* #[KnoxSSO Setup and Configuration]
Modified: knox/trunk/books/0.11.0/book_gateway-details.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/book_gateway-details.md?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/trunk/books/0.11.0/book_gateway-details.md (original)
+++ knox/trunk/books/0.11.0/book_gateway-details.md Fri Feb 24 20:39:11 2017
@@ -95,6 +95,7 @@ In the Hortonworks Sandbox Ambari might
<<config_webappsec_provider.md>>
<<config_hadoop_auth_provider.md>>
<<config_preauth_sso_provider.md>>
+<<config_sso_cookie_provider.md>>
<<config_pac4j_provider.md>>
<<config_knox_sso.md>>
<<config_mutual_authentication_ssl.md>>
Added: knox/trunk/books/0.11.0/config_sso_cookie_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.11.0/config_sso_cookie_provider.md?rev=1784323&view=auto
==============================================================================
--- knox/trunk/books/0.11.0/config_sso_cookie_provider.md (added)
+++ knox/trunk/books/0.11.0/config_sso_cookie_provider.md Fri Feb 24 20:39:11 2017
@@ -0,0 +1,74 @@
+<!---
+ 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.
+--->
+
+### SSO Cookie Provider ###
+
+#### Overview ####
+The SSOCookieProvider enables the federation of the authentication event that occurred through KnoxSSO. KnoxSSO is a typical SP initiated websso mechanism that sets a cookie to be presented by browsers to participating applications and cryptographically verified.
+
+Knox Gateway needs a pluggable mechanism for consuming these cookies and federating the KnoxSSO authentication event as an asserted identity in its interaction with the Hadoop cluster for REST API invocations. This provider is useful when an application that is integrated with KnoxSSO for authentication also consumes REST APIs through the Knox Gateway.
+
+Based on our understanding of the websso flow it should behave like:
+
+* SSOCookieProvider checks for hadoop-jwt cookie and in its absence redirects to the configured SSO provider URL (knoxsso endpoint)
+* The configured Provider on the KnoxSSO endpoint challenges the user in a provider specific way (presents form, redirects to SAML IdP, etc)
+* The authentication provider on KnoxSSO validates the identity of the user through credentials/tokens
+* The WebSSO service exchanges the normalized Java Subject into a JWT token and sets it on the response as a cookie named hadoop-jwt
+* The WebSSO service then redirects the user agent back to the originally requested URL - the requested Knox service subsequent invocations will find the cookie in the incoming request and not need to engage the WebSSO service again until it expires.
+
+#### Configuration ####
+##### sandbox.xml Topology Example
+Configuring one of the cluster topologies to use the SSOCookieProvider instead of the out of the box ShiroProvider would look something like the following:
+
+```
+<?xml version="1.0" encoding="utf-8"?>
+<topology>
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://localhost:9443/gateway/idp/api/v1/websso</value>
+ </param>
+ </provider>
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ </provider>
+ </gateway>
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+</topology>
+```
+
+The following table describes the configuration options for the web app security provider:
+
+##### Descriptions #####
+
+Name | Description | Default
+---------|-----------
+sso.authentication.provider.url|Required parameter that indicates the location of the KnoxSSO endpoint and where to redirect the useragent when no SSO cookie is found in the incoming request.|N/A
+
Modified: knox/trunk/books/0.12.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/book.md?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/book.md (original)
+++ knox/trunk/books/0.12.0/book.md Fri Feb 24 20:39:11 2017
@@ -46,6 +46,7 @@
* #[PAM based Authentication]
* #[HadoopAuth Authentication Provider]
* #[Preauthenticated SSO Provider]
+ * #[SSO Cookie Provider]
* #[Pac4j Provider - CAS / OAuth / SAML / OpenID Connect]
* #[KnoxSSO Setup and Configuration]
* #[Mutual Authentication with SSL]
Modified: knox/trunk/books/0.12.0/book_gateway-details.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/book_gateway-details.md?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/book_gateway-details.md (original)
+++ knox/trunk/books/0.12.0/book_gateway-details.md Fri Feb 24 20:39:11 2017
@@ -95,6 +95,7 @@ In the Hortonworks Sandbox Ambari might
<<config_webappsec_provider.md>>
<<config_hadoop_auth_provider.md>>
<<config_preauth_sso_provider.md>>
+<<config_sso_cookie_provider.md>>
<<config_pac4j_provider.md>>
<<config_knox_sso.md>>
<<config_mutual_authentication_ssl.md>>
Added: knox/trunk/books/0.12.0/config_sso_cookie_provider.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/config_sso_cookie_provider.md?rev=1784323&view=auto
==============================================================================
--- knox/trunk/books/0.12.0/config_sso_cookie_provider.md (added)
+++ knox/trunk/books/0.12.0/config_sso_cookie_provider.md Fri Feb 24 20:39:11 2017
@@ -0,0 +1,74 @@
+<!---
+ 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.
+--->
+
+### SSO Cookie Provider ###
+
+#### Overview ####
+The SSOCookieProvider enables the federation of the authentication event that occurred through KnoxSSO. KnoxSSO is a typical SP initiated websso mechanism that sets a cookie to be presented by browsers to participating applications and cryptographically verified.
+
+Knox Gateway needs a pluggable mechanism for consuming these cookies and federating the KnoxSSO authentication event as an asserted identity in its interaction with the Hadoop cluster for REST API invocations. This provider is useful when an application that is integrated with KnoxSSO for authentication also consumes REST APIs through the Knox Gateway.
+
+Based on our understanding of the websso flow it should behave like:
+
+* SSOCookieProvider checks for hadoop-jwt cookie and in its absence redirects to the configured SSO provider URL (knoxsso endpoint)
+* The configured Provider on the KnoxSSO endpoint challenges the user in a provider specific way (presents form, redirects to SAML IdP, etc)
+* The authentication provider on KnoxSSO validates the identity of the user through credentials/tokens
+* The WebSSO service exchanges the normalized Java Subject into a JWT token and sets it on the response as a cookie named hadoop-jwt
+* The WebSSO service then redirects the user agent back to the originally requested URL - the requested Knox service subsequent invocations will find the cookie in the incoming request and not need to engage the WebSSO service again until it expires.
+
+#### Configuration ####
+##### sandbox.xml Topology Example
+Configuring one of the cluster topologies to use the SSOCookieProvider instead of the out of the box ShiroProvider would look something like the following:
+
+```
+<?xml version="1.0" encoding="utf-8"?>
+<topology>
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://localhost:9443/gateway/idp/api/v1/websso</value>
+ </param>
+ </provider>
+ <provider>
+ <role>identity-assertion</role>
+ <name>Default</name>
+ <enabled>true</enabled>
+ </provider>
+ </gateway>
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+</topology>
+```
+
+The following table describes the configuration options for the web app security provider:
+
+##### Descriptions #####
+
+Name | Description | Default
+---------|-----------
+sso.authentication.provider.url|Required parameter that indicates the location of the KnoxSSO endpoint and where to redirect the useragent when no SSO cookie is found in the incoming request.|N/A
+
Modified: knox/trunk/books/0.12.0/dev-guide/knoxsso_integration.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/dev-guide/knoxsso_integration.md?rev=1784323&r1=1784322&r2=1784323&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/dev-guide/knoxsso_integration.md (original)
+++ knox/trunk/books/0.12.0/dev-guide/knoxsso_integration.md Fri Feb 24 20:39:11 2017
@@ -59,15 +59,13 @@ In order to enable KnoxSSO, we need to c
<value>authcBasic</value>
</param>
</provider>
-
- <provider>
+ <provider>
<role>identity-assertion</role>
<name>Default</name>
<enabled>true</enabled>
</provider>
</gateway>
-
- <service>
+ <service>
<role>KNOXSSO</role>
<param>
<name>knoxsso.cookie.secure.only</name>
@@ -90,65 +88,56 @@ In order to see the end to end story and
```
<?xml version="1.0" encoding="utf-8"?>
- <topology>
- <gateway>
- <provider>
- <role>federation</role>
- <name>SSOCookieProvider</name>
- <enabled>true</enabled>
- <param>
- <name>sso.authentication.provider.url</name>
- <value>https://localhost:9443/gateway/idp/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>
-
- <service>
- <role>JOBTRACKER</role>
- <url>rpc://localhost:8050</url>
- </service>
-
- <service>
- <role>WEBHDFS</role>
- <url>http://localhost:50070/webhdfs</url>
- </service>
-
- <service>
- <role>WEBHCAT</role>
- <url>http://localhost:50111/templeton</url>
- </service>
-
- <service>
- <role>OOZIE</role>
- <url>http://localhost:11000/oozie</url>
- </service>
-
- <service>
- <role>WEBHBASE</role>
- <url>http://localhost:60080</url>
- </service>
-
- <service>
- <role>HIVE</role>
- <url>http://localhost:10001/cliservice</url>
- </service>
-
- <service>
- <role>RESOURCEMANAGER</role>
- <url>http://localhost:8088/ws</url>
- </service>
- </topology>
+<topology>
+ <gateway>
+ <provider>
+ <role>federation</role>
+ <name>SSOCookieProvider</name>
+ <enabled>true</enabled>
+ <param>
+ <name>sso.authentication.provider.url</name>
+ <value>https://localhost:9443/gateway/idp/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>
+ <service>
+ <role>JOBTRACKER</role>
+ <url>rpc://localhost:8050</url>
+ </service>
+ <service>
+ <role>WEBHDFS</role>
+ <url>http://localhost:50070/webhdfs</url>
+ </service>
+ <service>
+ <role>WEBHCAT</role>
+ <url>http://localhost:50111/templeton</url>
+ </service>
+ <service>
+ <role>OOZIE</role>
+ <url>http://localhost:11000/oozie</url>
+ </service>
+ <service>
+ <role>WEBHBASE</role>
+ <url>http://localhost:60080</url>
+ </service>
+ <service>
+ <role>HIVE</role>
+ <url>http://localhost:10001/cliservice</url>
+ </service>
+ <service>
+ <role>RESOURCEMANAGER</role>
+ <url>http://localhost:8088/ws</url>
+ </service>
+</topology>
```
* NOTE: Be aware that when using Chrome as your browser that cookies don’t seem to work for “localhost”. Either use a VM or like I did - use 127.0.0.1. Safari works with localhost without problems.