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/03/16 05:26:41 UTC
svn commit: r1787123 - in /knox: site/books/knox-0-12-0/user-guide.html
trunk/books/0.12.0/book.md trunk/books/0.12.0/book_gateway-details.md
Author: lmccay
Date: Thu Mar 16 05:26:41 2017
New Revision: 1787123
URL: http://svn.apache.org/viewvc?rev=1787123&view=rev
Log:
adding docs for KnoxToken service to 0.12.0
Modified:
knox/site/books/knox-0-12-0/user-guide.html
knox/trunk/books/0.12.0/book.md
knox/trunk/books/0.12.0/book_gateway-details.md
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=1787123&r1=1787122&r2=1787123&view=diff
==============================================================================
--- knox/site/books/knox-0-12-0/user-guide.html (original)
+++ knox/site/books/knox-0-12-0/user-guide.html Thu Mar 16 05:26:41 2017
@@ -44,6 +44,7 @@
<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="#KnoxToken+service">KnoxToken service</a></li>
<li><a href="#Mutual+Authentication+with+SSL">Mutual Authentication with SSL</a></li>
</ul></li>
<li><a href="#Authorization">Authorization</a></li>
@@ -2895,7 +2896,52 @@ APACHE_HOME/bin/apachectl -k stop
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><p>Individual UIs within the Hadoop ecosystem will have similar configuration for participating in the KnoxSSO websso capabilities.</p><p>Blogs will be provided on the Apache Knox project site for these usecases as they become available.</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. R
ather 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>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><p>Individual UIs within the Hadoop ecosystem will have similar configuration for participating in the KnoxSSO websso capabilities.</p><p>Blogs will be provided on the Apache Knox project site for these usecases as they become available.</p><h2><a id="KnoxToken+Configuration">KnoxToken Configuration</a> <a href="#KnoxToken+Configuration"><img src="markbook-section-link.png"/></a></h2><h3><a id="Introduction">Introduction</a> <a href="#Introduction"><img src="markbook-section-link.png"/></a></h3>
+<hr/><p>The Knox Token Service enables the ability for clients to acquire the same JWT token that is used for KnoxSSO with WebSSO flows for UIs to be used for accessing REST APIs. By acquiring the token and setting it as a Bearer token on a request, a client is able to access REST APIs that are protected with the JWTProvider federation provider.</p><p>This section describes the overall setup requirements and options for KnoxToken service.</p><h3><a id="KnoxToken+service">KnoxToken service</a> <a href="#KnoxToken+service"><img src="markbook-section-link.png"/></a></h3><p>The Knox Token Service configuration can be configured in any topology and be tailored to issue tokens to authenticated users and constrain the usage of the tokens in a number of ways.</p>
+<pre><code><service>
+ <role>KNOXTOKEN</role>
+ <param>
+ <name>knox.token.ttl</name>
+ <value>36000000</value>
+ </param>
+ <param>
+ <name>knox.token.audiences</name>
+ <value>tokenbased</value>
+ </param>
+ <param>
+ <name>knox.token.target.url</name>
+ <value>https://localhost:8443/gateway/tokenbased</value>
+ </param>
+</service>
+</code></pre><h4><a id="KnoxToken+Configuration+Parameters">KnoxToken Configuration Parameters</a> <a href="#KnoxToken+Configuration+Parameters"><img src="markbook-section-link.png"/></a></h4>
+<table>
+ <thead>
+ <tr>
+ <th>Parameter </th>
+ <th>Description </th>
+ <th>Default</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>knox.token.ttl </td>
+ <td>This indicates the lifespan of the token. Once it expires a new token must be acquired from KnoxToken service. 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>knox.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 endpoint has expected audiences and they are not present the token must be rejected. In the event where the token has audiences and the endpoint has none expected then the token is accepted.</td>
+ <td>empty</td>
+ </tr>
+ <tr>
+ <td>knox.token.target.url </td>
+ <td>This is an optional configuration parameter to indicate the intended endpoint for which the token may be used. The KnoxShell token credential collector can pull this URL from a knoxtokencache file to be used in scripts. This eliminates the need to prompt for or hardcode endpoints in your scripts. </td>
+ <td>n/a</td>
+ </tr>
+ </tbody>
+</table><p>Adding the KnoxToken configuration show above to a topology that is protected with the ShrioProvider is a very simple and effective way to expose an endpoint from which a Knox token can be requested. Once it is acquired it may be used to access resources at intended endpoints until it expires.</p><p>The following curl example shows how to add a bearer token to an Authorization header:</p>
+<pre><code>curl -ivku guest:guest-password -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJndWVzdCIsImF1ZCI6InRva2VuYmFzZWQiLCJpc3MiOiJLTk9YU1NPIiwiZXhwIjoxNDg5OTI3MTM1fQ.HFxcUtg1Id9t7HOjHkxXsfZE1jB1nd2g9l71cFsgWvT3nsrIuHOzfFdhQwQYsrPqA5h2VZ1UuqOqajI0e_gCOlwoslm3ZD9xMkU2g2qGG81Ao3vvmaaLs8EE0_VuFq5ZHt08ls3oyzjWUKlb2VSrNOjzWjHyoHi_k2M04r9grp8" https://localhost:8443/gateway/tokenbased/webhdfs/v1/tmp?op=LISTSTATUS
+</code></pre><p>See documentation in Client Details for KnoxShell init, list and destroy for commands that leverage this token service for CLI sessions.</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, connectio
ns 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/trunk/books/0.12.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.12.0/book.md?rev=1787123&r1=1787122&r2=1787123&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/book.md (original)
+++ knox/trunk/books/0.12.0/book.md Thu Mar 16 05:26:41 2017
@@ -49,6 +49,7 @@
* #[SSO Cookie Provider]
* #[Pac4j Provider - CAS / OAuth / SAML / OpenID Connect]
* #[KnoxSSO Setup and Configuration]
+ * #[KnoxToken service]
* #[Mutual Authentication with SSL]
* #[Authorization]
* #[Identity Assertion]
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=1787123&r1=1787122&r2=1787123&view=diff
==============================================================================
--- knox/trunk/books/0.12.0/book_gateway-details.md (original)
+++ knox/trunk/books/0.12.0/book_gateway-details.md Thu Mar 16 05:26:41 2017
@@ -98,6 +98,7 @@ In the Hortonworks Sandbox Ambari might
<<config_sso_cookie_provider.md>>
<<config_pac4j_provider.md>>
<<config_knox_sso.md>>
+<<config_knox_token.md>>
<<config_mutual_authentication_ssl.md>>
<<websocket-support.md>>
<<config_audit.md>>