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.
![https://pac4j.github.io/pac4j/img/logo-knox.png"](https://pac4j.github.io/pac4j/img/logo-knox.png"){kind=link}