Author: pzampino
Date: Sat Mar 14 17:46:13 2020
New Revision: 1875194
URL: http://svn.apache.org/viewvc?rev=1875194&view=rev
Log:
Updated KnoxToken service and JWT Provider descriptions for server-managed
state and renewal / revocation
Modified:
knox/site/books/knox-0-12-0/deployment-overview.png
knox/site/books/knox-0-12-0/deployment-provider.png
knox/site/books/knox-0-12-0/deployment-service.png
knox/site/books/knox-0-12-0/general_saml_flow.png
knox/site/books/knox-0-12-0/runtime-overview.png
knox/site/books/knox-0-12-0/runtime-request-processing.png
knox/site/books/knox-0-13-0/deployment-overview.png
knox/site/books/knox-0-13-0/deployment-provider.png
knox/site/books/knox-0-13-0/deployment-service.png
knox/site/books/knox-0-13-0/general_saml_flow.png
knox/site/books/knox-0-13-0/runtime-overview.png
knox/site/books/knox-0-13-0/runtime-request-processing.png
knox/site/books/knox-0-14-0/deployment-overview.png
knox/site/books/knox-0-14-0/deployment-provider.png
knox/site/books/knox-0-14-0/deployment-service.png
knox/site/books/knox-0-14-0/general_saml_flow.png
knox/site/books/knox-0-14-0/runtime-overview.png
knox/site/books/knox-0-14-0/runtime-request-processing.png
knox/site/books/knox-1-0-0/deployment-overview.png
knox/site/books/knox-1-0-0/deployment-provider.png
knox/site/books/knox-1-0-0/deployment-service.png
knox/site/books/knox-1-0-0/general_saml_flow.png
knox/site/books/knox-1-0-0/runtime-overview.png
knox/site/books/knox-1-0-0/runtime-request-processing.png
knox/site/books/knox-1-1-0/deployment-overview.png
knox/site/books/knox-1-1-0/deployment-provider.png
knox/site/books/knox-1-1-0/deployment-service.png
knox/site/books/knox-1-1-0/general_saml_flow.png
knox/site/books/knox-1-1-0/runtime-overview.png
knox/site/books/knox-1-1-0/runtime-request-processing.png
knox/site/books/knox-1-2-0/deployment-overview.png
knox/site/books/knox-1-2-0/deployment-provider.png
knox/site/books/knox-1-2-0/deployment-service.png
knox/site/books/knox-1-2-0/general_saml_flow.png
knox/site/books/knox-1-2-0/runtime-overview.png
knox/site/books/knox-1-2-0/runtime-request-processing.png
knox/site/books/knox-1-3-0/deployment-overview.png
knox/site/books/knox-1-3-0/deployment-provider.png
knox/site/books/knox-1-3-0/deployment-service.png
knox/site/books/knox-1-3-0/general_saml_flow.png
knox/site/books/knox-1-3-0/runtime-overview.png
knox/site/books/knox-1-3-0/runtime-request-processing.png
knox/site/books/knox-1-4-0/deployment-overview.png
knox/site/books/knox-1-4-0/deployment-provider.png
knox/site/books/knox-1-4-0/deployment-service.png
knox/site/books/knox-1-4-0/general_saml_flow.png
knox/site/books/knox-1-4-0/runtime-overview.png
knox/site/books/knox-1-4-0/runtime-request-processing.png
knox/site/books/knox-1-4-0/user-guide.html
knox/site/index.html
knox/site/issue-management.html
knox/site/licenses.html
knox/site/mailing-lists.html
knox/site/project-info.html
knox/site/team.html
knox/trunk/books/1.4.0/book_client-details.md
knox/trunk/books/1.4.0/config.md
knox/trunk/books/1.4.0/config_knox_token.md
knox/trunk/books/1.4.0/config_sso_cookie_provider.md
Modified: knox/site/books/knox-0-12-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-12-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-12-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-13-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-13-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-14-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-14-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-14-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-14-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-14-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-0-14-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-14-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-0-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-0-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-0-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-0-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-0-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-0-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-0-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-0-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-0-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-0-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-0-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-0-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-1-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-1-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-1-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-1-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-1-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-1-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-1-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-2-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-2-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-2-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-2-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-2-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-2-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-2-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-2-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-2-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-2-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-2-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-2-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-3-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-3-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-3-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-3-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-3-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-3-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-3-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-4-0/deployment-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/deployment-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-4-0/deployment-provider.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/deployment-provider.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-4-0/deployment-service.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/deployment-service.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-4-0/general_saml_flow.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/general_saml_flow.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-4-0/runtime-overview.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/runtime-overview.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-4-0/runtime-request-processing.png
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/runtime-request-processing.png?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
Binary files - no diff available.
Modified: knox/site/books/knox-1-4-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-1-4-0/user-guide.html?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/site/books/knox-1-4-0/user-guide.html (original)
+++ knox/site/books/knox-1-4-0/user-guide.html Sat Mar 14 17:46:13 2020
@@ -988,6 +988,21 @@ https://{gateway-host}:{gateway-port}/{g
<td>Add service name to x-forward-context header for the defined list of
services. </td>
<td><code>LIVYSERVER</code></td>
</tr>
+ <tr>
+ <td><code>gateway.knox.token.exp.server-managed</code> </td>
+ <td>Default server-managed token state configuration for all KnoxToken
service and JWT provider deployments </td>
+ <td><code>false</code></td>
+ </tr>
+ <tr>
+ <td><code>gateway.knox.token.eviction.interval</code> </td>
+ <td>The period about which the token state reaper will evict state for
expired tokens. This configuration only applies when server-managed token state
is enabled either in gateway-site or at the topology level. </td>
+ <td><code>300000</code> (5 minutes)</td>
+ </tr>
+ <tr>
+ <td><code>gateway.knox.token.eviction.grace.period</code> </td>
+ <td>A duration (milliseconds) beyond a token’s expiration to wait
before evicting its state. This configuration only applies when server-managed
token state is enabled either in gateway-site or at the topology level. </td>
+ <td><code>300000</code> (5 minutes)</td>
+ </tr>
</tbody>
</table>
<h4><a id="Topology+Descriptors">Topology Descriptors</a> <a
href="#Topology+Descriptors"><img src="markbook-section-link.png"/></a></h4>
@@ -4751,35 +4766,40 @@ APACHE_HOME/bin/apachectl -k stop
<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>
+<h5><a id="sandbox.json+Topology+Example">sandbox.json Topology Example</a> <a
href="#sandbox.json+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>
+<p>sso-provider.json</p>
+<pre><code>{
+ "providers": [
+ {
+ "role": "federation",
+ "name": "SSOCookieProvider",
+ "enabled": "true",
+ "params": {
+ "sso.authentication.provider.url":
"https://localhost:9443/gateway/idp/api/v1/websso"
+ }
+ }
+ ]
+}
+</code></pre>
+<p>sandbox.json</p>
+<pre><code>{
+ "provider-config-ref": "sso-provider",
+ "services": [
+ {
+ "name": "WEBHDFS",
+ "urls": [
+ "http://localhost:50070/webhdfs"
+ ]
+ },
+ {
+ "name": "WEBHCAT",
+ "urls": [
+ "http://localhost:50111/templeton"
+ ]
+ }
+ ]
+}
</code></pre>
<p>The following table describes the configuration options for the sso cookie
provider:</p>
<h5><a id="Descriptions">Descriptions</a> <a href="#Descriptions"><img
src="markbook-section-link.png"/></a></h5>
@@ -4802,18 +4822,18 @@ APACHE_HOME/bin/apachectl -k stop
<h3><a id="JWT+Provider">JWT Provider</a> <a href="#JWT+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 JWT federation provider accepts JWT tokens as Bearer tokens within the
Authorization header of the incoming request. Upon successfully extracting and
verifying the token, the request is then processed on behalf of the user
represented by the JWT token.</p>
-<p>This provider is closely related to the Knox Token Service and is
essentially the provider that is used to consume the tokens issued by the Knox
Token Service.</p>
-<p>Typical deployments have the KnoxToken service defined in a topology such
as <code>sandbox.xml</code> that authenticates users based on username and
password which as with the ShiroProvider. They also have a topology dedicated
to clients that wish to use KnoxTokens to access Hadoop resources through Knox.
</p>
-<p>The following provider configuration can be used within such a topology.</p>
-<pre><code><provider>
- <role>federation</role>
- <name>JWTProvider</name>
- <enabled>true</enabled>
- <param>
- <name>knox.token.audiences</name>
- <value>tokenbased</value>
- </param>
-</provider>
+<p>This provider is closely related to the <a
href="#KnoxToken+Configuration">Knox Token Service</a> and is essentially the
provider that is used to consume the tokens issued by the <a
href="#KnoxToken+Configuration">Knox Token Service</a>.</p>
+<p>Typical deployments have the KnoxToken service defined in a topology that
authenticates users based on username and password with the ShiroProvider. They
also have another topology dedicated to clients that wish to use KnoxTokens to
access Hadoop resources through Knox. The following provider configuration can
be used with such a topology.</p>
+<pre><code>"providers": [
+ {
+ "role": "federation",
+ "name": "JWTProvider",
+ "enabled": "true",
+ "params": {
+ "knox.token.audiences": "tokenbased"
+ }
+ }
+]
</code></pre>
<p>The <code>knox.token.audiences</code> parameter above indicates that any
token in an incoming request must contain an audience claim called
“tokenbased”. In this case, the idea is that the issuing KnoxToken
service will be configured to include such an audience claim and that the
resulting token is valid to use in the topology that contains configuration
like above. This would generally be the name of the topology but you can
standardize on anything.</p>
<p>The following table describes the configuration options for the JWT
federation provider:</p>
@@ -4832,9 +4852,15 @@ APACHE_HOME/bin/apachectl -k stop
<td>Optional parameter. This parameter allows the administrator to
constrain the use of tokens on this endpoint to those that have tokens with at
least one of the configured audience claims. These claims have associated
configuration within the KnoxToken service as well. This provides an
interesting way to make sure that the token issued based on authentication to a
particular LDAP server or other IdP is accepted but not others.</td>
<td>N/A</td>
</tr>
+ <tr>
+ <td>knox.token.exp.server-managed </td>
+ <td>Optional parameter for specifying that server-managed token state
should be referenced for evaluating token validity. </td>
+ <td>false</td>
+ </tr>
</tbody>
</table>
-<p>See the documentation for the Knox Token service for related details.</p>
+<p>The optional <code>knox.token.exp.server-managed</code> parameter indicates
that Knox is managing the state of tokens it issues (e.g., expiration) external
from the token, and this external state should be referenced when validating
tokens. This parameter can be ommitted if the global default is configured in
gateway-site (see <a
href="#Gateway+Server+Configuration">gateway.knox.token.exp.server-managed</a>),
and matches the requirements of this provider. Otherwise, this provider
parameter overrides the gateway configuration for the provider’s
deployment.</p>
+<p>See the <a href="#KnoxToken+Configuration">documentation for the Knox Token
service</a> for related details.</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>
<p align="center">
<img src="https://www.pac4j.org/img/logo-knox.png"; width="300" />
@@ -5266,22 +5292,21 @@ APACHE_HOME/bin/apachectl -k stop
<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>
+<p>The Knox Token Service configuration can be configured in any
descriptor/topology, tailored to issue tokens to authenticated users, and
constrain the usage of the tokens in a number of ways.</p>
+<pre><code>"services": [
+ {
+ "name": "KNOXTOKEN",
+ "params": {
+ "knox.token.ttl": "36000000",
+ "knox.token.audiences": "tokenbased",
+ "knox.token.target.url":
"https://localhost:8443/gateway/tokenbased",
+ "knox.token.exp.server-managed": "false",
+ "knox.token.renewer.whitelist": "admin",
+ "knox.token.exp.renew-interval": "86400000",
+ "knox.token.exp.max-lifetime": "604800000"
+ }
+ }
+]
</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>
@@ -5289,27 +5314,48 @@ APACHE_HOME/bin/apachectl -k stop
<tr>
<th>Parameter </th>
<th>Description </th>
- <th>Default</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>
+ <td>This indicates the lifespan (milliseconds) of the token. Once it
expires a new token must be acquired from KnoxToken service. The 36000000 in
the topology above gives you 10 hrs. </td>
+ <td>30000 (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>
+ <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>
+ <td>n/a </td>
+ </tr>
+ <tr>
+ <td>knox.token.exp.server-managed </td>
+ <td>This is an optional configuration parameter to enable/disable
server-managed token state, to support the associated token renewal and
revocation APIs. </td>
+ <td>false </td>
+ </tr>
+ <tr>
+ <td>knox.token.renewer.whitelist </td>
+ <td>This is an optional configuration parameter to authorize the
comma-separated list of users to invoke the associated token renewal and
revocation APIs. </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td>knox.token.exp.renew-interval </td>
+ <td>This is an optional configuration parameter to specify the amount of
time (milliseconds) to be added to a token’s TTL when a renewal request
is approved. </td>
+ <td>86400000 (24 hours) </td>
+ </tr>
+ <tr>
+ <td>knox.token.exp.max-lifetime </td>
+ <td>This is an optional configuration parameter to specify the maximum
allowed lifetime (milliseconds) of a token, after which renewal will not be
permitted. </td>
+ <td>604800000 (7 days) </td>
</tr>
</tbody>
</table>
+<p>Note that server-managed token state can be configured for all KnoxToken
service deployments in gateway-site (see <a
href="#Gateway+Server+Configuration">gateway.knox.token.exp.server-managed</a>).
If it is configured at the gateway level, then the associated service
parameter, if configured, will override the gateway configuration.</p>
<p>Adding the KnoxToken configuration shown 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 command can be used to acquire a token from the Knox
Token service as configured in the sandbox topology:</p>
<pre><code>curl -ivku guest:guest-password
https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token
@@ -5320,6 +5366,52 @@ APACHE_HOME/bin/apachectl -k stop
<p>The following curl example shows how to add a bearer token to an
Authorization header:</p>
<pre><code>curl -ivk -H "Authorization: Bearer
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJndWVzdCIsImF1ZCI6InRva2VuYmFzZWQiLCJpc3MiOiJLTk9YU1NPIiwiZXhwIjoxNDg5OTQyMTg4fQ.bcqSK7zMnABEM_HVsm3oWNDrQ_ei7PcMI4AtZEERY9LaPo9dzugOg3PA5JH2BRF-lXM3tuEYuZPaZVf8PenzjtBbuQsCg9VVImuu2r1YNVJlcTQ7OV-eW50L6OTI0uZfyrFwX6C7jVhf7d7YR1NNxs4eVbXpS1TZ5fDIRSfU3MU"
https://localhost:8443/gateway/tokenbased/webhdfs/v1/tmp?op=LISTSTATUS
</code></pre>
+<h4><a id="KnoxToken+Renewal+and+Revocation">KnoxToken Renewal and
Revocation</a> <a href="#KnoxToken+Renewal+and+Revocation"><img
src="markbook-section-link.png"/></a></h4>
+<p>The KnoxToken service supports the renewal and explicit revocation of
tokens it has issued. Support for both requires server-managed token state to
be enabled with at least one renewer white-listed.</p>
+<h5><a id="Renewal">Renewal</a> <a href="#Renewal"><img
src="markbook-section-link.png"/></a></h5>
+<pre><code>curl -ivku admin:admin-password -X POST -d $TOKEN
'https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/renew'
+</code></pre>
+<p>The JSON responses include a flag indicating success or failure.</p>
+<p>A successful result includes the updated expiration time.</p>
+<pre><code>{
+ "renewed": "true",
+ "expires": "1584278311658"
+}
+</code></pre>
+<p>Error results include a message describing the reason for failure.</p>
+<p>Invalid token</p>
+<pre><code>{
+ "renewed": "false",
+ "error": "Unknown token:
9caf743e-1e0d-4708-a9ac-a684a576067c"
+}
+</code></pre>
+<p>Unauthorized caller</p>
+<pre><code>{
+ "renewed": "false",
+ "error": "Caller (guest) not authorized to renew tokens."
+}
+</code></pre>
+<h5><a id="Revocation">Revocation</a> <a href="#Revocation"><img
src="markbook-section-link.png"/></a></h5>
+<pre><code>curl -ivku admin:admin-password -X POST -d $TOKEN
'https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke'
+</code></pre>
+<p>The JSON responses include a flag indicating success or failure.</p>
+<pre><code>{
+ "revoked": "true"
+}
+</code></pre>
+<p>Error results include a message describing the reason for the failure.</p>
+<p>Invalid token</p>
+<pre><code>{
+ "revoked": "false",
+ "error": "Unknown token:
9caf743e-1e0d-4708-a9ac-a684a576067c"
+}
+</code></pre>
+<p>Unauthorized caller</p>
+<pre><code>{
+ "revoked": "false",
+ "error": "Caller (guest) not authorized to revoke
tokens."
+}
+</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>
@@ -5629,35 +5721,31 @@ session.shutdown()
<h4><a id="Server+Setup">Server Setup</a> <a href="#Server+Setup"><img
src="markbook-section-link.png"/></a></h4>
<ol>
<li>
- <p>KnoxToken service should be added to your <code>sandbox.xml</code>
topology - see the <a href="#KnoxToken+Configuration">KnoxToken Configuration
Section</a></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>
+ <p>KnoxToken service should be added to your <code>sandbox</code>
descriptor - see the <a href="#KnoxToken+Configuration">KnoxToken
Configuration</a></p>
+ <pre><code>"services": [
+ {
+ "name": "KNOXTOKEN",
+ "params": {
+ "knox.token.ttl": "36000000",
+ "knox.token.audiences": "tokenbased",
+ "knox.token.target.url":
"https://localhost:8443/gateway/tokenbased"
+ }
+ }
+]
</code></pre>
</li>
<li>
- <p><code>tokenbased.xml</code> topology to accept tokens as federation
tokens for access to exposed resources with JWTProvider <a
href="#JWT+Provider">JWT Provider</a></p>
- <pre><code><provider>
- <role>federation</role>
- <name>JWTProvider</name>
- <enabled>true</enabled>
- <param>
- <name>knox.token.audiences</name>
- <value>tokenbased</value>
- </param>
-</provider>
+ <p>Include the following in the provider configuration referenced from the
<code>tokenbased</code> descriptor to accept tokens as federation tokens for
access to exposed resources with the <a href="#JWT+Provider">JWTProvider</a></p>
+ <pre><code>"providers": [
+ {
+ "role": "federation",
+ "name": "JWTProvider",
+ "enabled": "true",
+ "params": {
+ "knox.token.audiences": "tokenbased"
+ }
+ }
+]
</code></pre>
</li>
<li>
@@ -5669,12 +5757,12 @@ session.shutdown()
</ul>
</li>
<li>
- <p>Execute a script that can take advantage of the token credential
collector and target url</p>
+ <p>Execute a script that can take advantage of the token credential
collector and target URL</p>
<pre><code>import groovy.json.JsonSlurper
import java.util.HashMap
import java.util.Map
import org.apache.knox.gateway.shell.Credentials
-import org.apache.knox.gateway.shell.Hadoop
+import org.apache.knox.gateway.shell.KnoxSession
import org.apache.knox.gateway.shell.hdfs.Hdfs
credentials = new Credentials()
@@ -5697,7 +5785,7 @@ println ""
headers = new HashMap()
headers.put("Authorization", "Bearer " + token)
-session = Hadoop.login( gateway, headers )
+session = KnoxSession.login( gateway, headers )
if (args.length > 0) {
dir = args[0]
Modified: knox/site/index.html
URL:
http://svn.apache.org/viewvc/knox/site/index.html?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Sat Mar 14 17:46:13 2020
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2020-03-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2020-03-14
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20200313" />
+ <meta name="Date-Revision-yyyymmdd" content="20200314" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Announcing Apache Knox 1.3.0!</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2020-03-13</li>
+ <li id="publishDate">Last Published: 2020-03-14</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/issue-management.html
URL:
http://svn.apache.org/viewvc/knox/site/issue-management.html?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/site/issue-management.html (original)
+++ knox/site/issue-management.html Sat Mar 14 17:46:13 2020
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:issue-management
at 2020-03-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:issue-management
at 2020-03-14
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20200313" />
+ <meta name="Date-Revision-yyyymmdd" content="20200314" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Issue Management</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2020-03-13</li>
+ <li id="publishDate">Last Published: 2020-03-14</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/licenses.html
URL:
http://svn.apache.org/viewvc/knox/site/licenses.html?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/site/licenses.html (original)
+++ knox/site/licenses.html Sat Mar 14 17:46:13 2020
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:licenses at
2020-03-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:licenses at
2020-03-14
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20200313" />
+ <meta name="Date-Revision-yyyymmdd" content="20200314" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Licenses</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2020-03-13</li>
+ <li id="publishDate">Last Published: 2020-03-14</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/mailing-lists.html
URL:
http://svn.apache.org/viewvc/knox/site/mailing-lists.html?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/site/mailing-lists.html (original)
+++ knox/site/mailing-lists.html Sat Mar 14 17:46:13 2020
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:mailing-lists
at 2020-03-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:mailing-lists
at 2020-03-14
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20200313" />
+ <meta name="Date-Revision-yyyymmdd" content="20200314" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Mailing Lists</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2020-03-13</li>
+ <li id="publishDate">Last Published: 2020-03-14</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/project-info.html
URL:
http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Sat Mar 14 17:46:13 2020
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-site-plugin:3.7.1:CategorySummaryDocumentRenderer
at 2020-03-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-site-plugin:3.7.1:CategorySummaryDocumentRenderer
at 2020-03-14
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20200313" />
+ <meta name="Date-Revision-yyyymmdd" content="20200314" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Information</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2020-03-13</li>
+ <li id="publishDate">Last Published: 2020-03-14</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/team.html
URL:
http://svn.apache.org/viewvc/knox/site/team.html?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/site/team.html (original)
+++ knox/site/team.html Sat Mar 14 17:46:13 2020
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:team at
2020-03-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:team at
2020-03-14
| Rendered using Apache Maven Fluido Skin 1.7
-->
<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="20200313" />
+ <meta name="Date-Revision-yyyymmdd" content="20200314" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Team</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -40,7 +40,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2020-03-13</li>
+ <li id="publishDate">Last Published: 2020-03-14</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/trunk/books/1.4.0/book_client-details.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/book_client-details.md?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/trunk/books/1.4.0/book_client-details.md (original)
+++ knox/trunk/books/1.4.0/book_client-details.md Sat Mar 14 17:46:13 2020
@@ -104,48 +104,45 @@ Building on the Quickstart above we will
Unlike the quickstart, token sessions require the server to be configured in
specific ways to allow the use of token sessions/federation.
#### Server Setup ####
-1. KnoxToken service should be added to your `sandbox.xml` topology - see the
[KnoxToken Configuration Section] (#KnoxToken+Configuration)
+1. KnoxToken service should be added to your `sandbox` descriptor - see the
[KnoxToken Configuration] (#KnoxToken+Configuration)
+
+ "services": [
+ {
+ "name": "KNOXTOKEN",
+ "params": {
+ "knox.token.ttl": "36000000",
+ "knox.token.audiences": "tokenbased",
+ "knox.token.target.url":
"https://localhost:8443/gateway/tokenbased";
+ }
+ }
+ ]
+
+2. Include the following in the provider configuration referenced from the
`tokenbased` descriptor to accept tokens as federation tokens for access to
exposed resources with the [JWTProvider](#JWT+Provider)
+
+ "providers": [
+ {
+ "role": "federation",
+ "name": "JWTProvider",
+ "enabled": "true",
+ "params": {
+ "knox.token.audiences": "tokenbased"
+ }
+ }
+ ]
- <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>
-
-2. `tokenbased.xml` topology to accept tokens as federation tokens for access
to exposed resources with JWTProvider [JWT Provider](#JWT+Provider)
-
- <provider>
- <role>federation</role>
- <name>JWTProvider</name>
- <enabled>true</enabled>
- <param>
- <name>knox.token.audiences</name>
- <value>tokenbased</value>
- </param>
- </provider>
3. Use the KnoxShell token commands to establish and manage your session
- bin/knoxshell.sh init https://localhost:8443/gateway/sandbox to acquire
a token and cache in user home directory
- bin/knoxshell.sh list to display the details of the cached token, the
expiration time and optionally the target url
- bin/knoxshell destroy to remove the cached session token and terminate
the session
-4. Execute a script that can take advantage of the token credential collector
and target url
+4. Execute a script that can take advantage of the token credential collector
and target URL
import groovy.json.JsonSlurper
import java.util.HashMap
import java.util.Map
import org.apache.knox.gateway.shell.Credentials
- import org.apache.knox.gateway.shell.Hadoop
+ import org.apache.knox.gateway.shell.KnoxSession
import org.apache.knox.gateway.shell.hdfs.Hdfs
credentials = new Credentials()
@@ -168,7 +165,7 @@ Unlike the quickstart, token sessions re
headers = new HashMap()
headers.put("Authorization", "Bearer " + token)
- session = Hadoop.login( gateway, headers )
+ session = KnoxSession.login( gateway, headers )
if (args.length > 0) {
dir = args[0]
@@ -195,6 +192,9 @@ Note the following about the above sampl
Also note that there is no reason to prompt for username and password as long
as the token has not been destroyed or expired.
There is also no hardcoded endpoint for using the token - it is specified in
the token cache or overridden by environment variable.
+
+
+
## Client DSL and SDK Details ##
The lack of any formal SDK or client for REST APIs in Hadoop led to thinking
about a very simple client that could help people use and evaluate the gateway.
Modified: knox/trunk/books/1.4.0/config.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config.md?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/trunk/books/1.4.0/config.md (original)
+++ knox/trunk/books/1.4.0/config.md Sat Mar 14 17:46:13 2020
@@ -167,6 +167,9 @@ Property | Description | Default
`gateway.strict.topology.validation` | If true, topology XML files will be
validated against the topology schema during redeploy | `false`
`gateway.global.rules.services` | Set the list of service names that have
global rules, all services that are not in this list have rules that are
treated as scoped to only to that service. | `"NAMENODE","JOBTRACKER",
"WEBHDFS", "WEBHCAT", "OOZIE", "WEBHBASE", "HIVE", "RESOURCEMANAGER"`
`gateway.xforwarded.header.context.append.servicename` | Add service name to
x-forward-context header for the defined list of services. | `LIVYSERVER`
+`gateway.knox.token.exp.server-managed` | Default server-managed token state
configuration for all KnoxToken service and JWT provider deployments | `false`
+`gateway.knox.token.eviction.interval` | The period about which the token
state reaper will evict state for expired tokens. This configuration only
applies when server-managed token state is enabled either in gateway-site or at
the topology level. | `300000` (5 minutes)
+`gateway.knox.token.eviction.grace.period` | A duration (milliseconds) beyond
a token's expiration to wait before evicting its state. This configuration only
applies when server-managed token state is enabled either in gateway-site or at
the topology level. | `300000` (5 minutes)
#### Topology Descriptors ####
Modified: knox/trunk/books/1.4.0/config_knox_token.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_knox_token.md?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/trunk/books/1.4.0/config_knox_token.md (original)
+++ knox/trunk/books/1.4.0/config_knox_token.md Sat Mar 14 17:46:13 2020
@@ -8,31 +8,36 @@ The Knox Token Service enables the abili
This section describes the overall setup requirements and options for
KnoxToken service.
### KnoxToken service
-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.
+The Knox Token Service configuration can be configured in any
descriptor/topology, tailored to issue tokens to authenticated users, and
constrain the usage of the tokens in a number of ways.
- <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>
+ "services": [
+ {
+ "name": "KNOXTOKEN",
+ "params": {
+ "knox.token.ttl": "36000000",
+ "knox.token.audiences": "tokenbased",
+ "knox.token.target.url":
"https://localhost:8443/gateway/tokenbased";,
+ "knox.token.exp.server-managed": "false",
+ "knox.token.renewer.whitelist": "admin",
+ "knox.token.exp.renew-interval": "86400000",
+ "knox.token.exp.max-lifetime": "604800000"
+ }
+ }
+ ]
#### KnoxToken Configuration Parameters
-Parameter | Description | Default
--------------------------------- |------------ |-----------
-knox.token.ttl | 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. | 30000 That
is 30 seconds.
-knox.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 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.| empty
-knox.token.target.url | 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. | n/a
+Parameter | Description | Default |
+-------------------------------- |------------ |----------- |
+knox.token.ttl | This indicates the lifespan (milliseconds) of
the token. Once it expires a new token must be acquired from KnoxToken service.
The 36000000 in the topology above gives you 10 hrs. | 30000 (30 seconds) |
+knox.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 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.| empty |
+knox.token.target.url | 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. | n/a |
+knox.token.exp.server-managed | This is an optional configuration parameter to
enable/disable server-managed token state, to support the associated token
renewal and revocation APIs. | false |
+knox.token.renewer.whitelist | This is an optional configuration parameter to
authorize the comma-separated list of users to invoke the associated token
renewal and revocation APIs. | |
+knox.token.exp.renew-interval | This is an optional configuration parameter to
specify the amount of time (milliseconds) to be added to a token's TTL when a
renewal request is approved. | 86400000 (24 hours) |
+knox.token.exp.max-lifetime | This is an optional configuration parameter to
specify the maximum allowed lifetime (milliseconds) of a token, after which
renewal will not be permitted. | 604800000 (7 days) |
+
+Note that server-managed token state can be configured for all KnoxToken
service deployments in gateway-site (see
[gateway.knox.token.exp.server-managed](#Gateway+Server+Configuration)). If it
is configured at the gateway level, then the associated service parameter, if
configured, will override the gateway configuration.
Adding the KnoxToken configuration shown 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.
@@ -48,4 +53,65 @@ The following curl example shows how to
curl -ivk -H "Authorization: Bearer
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJndWVzdCIsImF1ZCI6InRva2VuYmFzZWQiLCJpc3MiOiJLTk9YU1NPIiwiZXhwIjoxNDg5OTQyMTg4fQ.bcqSK7zMnABEM_HVsm3oWNDrQ_ei7PcMI4AtZEERY9LaPo9dzugOg3PA5JH2BRF-lXM3tuEYuZPaZVf8PenzjtBbuQsCg9VVImuu2r1YNVJlcTQ7OV-eW50L6OTI0uZfyrFwX6C7jVhf7d7YR1NNxs4eVbXpS1TZ5fDIRSfU3MU"
https://localhost:8443/gateway/tokenbased/webhdfs/v1/tmp?op=LISTSTATUS
+#### KnoxToken Renewal and Revocation
+
+The KnoxToken service supports the renewal and explicit revocation of tokens
it has issued.
+Support for both requires server-managed token state to be enabled with at
least one renewer white-listed.
+
+##### Renewal
+
+ curl -ivku admin:admin-password -X POST -d $TOKEN
'https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/renew'
+
+The JSON responses include a flag indicating success or failure.
+
+A successful result includes the updated expiration time.
+
+ {
+ "renewed": "true",
+ "expires": "1584278311658"
+ }
+
+Error results include a message describing the reason for failure.
+
+Invalid token
+
+ {
+ "renewed": "false",
+ "error": "Unknown token: 9caf743e-1e0d-4708-a9ac-a684a576067c"
+ }
+
+Unauthorized caller
+
+ {
+ "renewed": "false",
+ "error": "Caller (guest) not authorized to renew tokens."
+ }
+
+##### Revocation
+
+ curl -ivku admin:admin-password -X POST -d $TOKEN
'https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke'
+
+The JSON responses include a flag indicating success or failure.
+
+ {
+ "revoked": "true"
+ }
+
+Error results include a message describing the reason for the failure.
+
+Invalid token
+
+ {
+ "revoked": "false",
+ "error": "Unknown token: 9caf743e-1e0d-4708-a9ac-a684a576067c"
+ }
+
+Unauthorized caller
+
+ {
+ "revoked": "false",
+ "error": "Caller (guest) not authorized to revoke tokens."
+ }
+
+
See documentation in Client Details for KnoxShell init, list and destroy for
commands that leverage this token service for CLI sessions.
\ No newline at end of file
Modified: knox/trunk/books/1.4.0/config_sso_cookie_provider.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/1.4.0/config_sso_cookie_provider.md?rev=1875194&r1=1875193&r2=1875194&view=diff
==============================================================================
--- knox/trunk/books/1.4.0/config_sso_cookie_provider.md (original)
+++ knox/trunk/books/1.4.0/config_sso_cookie_provider.md Sat Mar 14 17:46:13
2020
@@ -31,38 +31,43 @@ Based on our understanding of the WebSSO
* 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
+##### sandbox.json 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>
-```
+sso-provider.json
+
+ {
+ "providers": [
+ {
+ "role": "federation",
+ "name": "SSOCookieProvider",
+ "enabled": "true",
+ "params": {
+ "sso.authentication.provider.url":
"https://localhost:9443/gateway/idp/api/v1/websso";
+ }
+ }
+ ]
+ }
+
+sandbox.json
+
+ {
+ "provider-config-ref": "sso-provider",
+ "services": [
+ {
+ "name": "WEBHDFS",
+ "urls": [
+ "http://localhost:50070/webhdfs";
+ ]
+ },
+ {
+ "name": "WEBHCAT",
+ "urls": [
+ "http://localhost:50111/templeton";
+ ]
+ }
+ ]
+ }
The following table describes the configuration options for the sso cookie
provider:
@@ -77,21 +82,21 @@ sso.authentication.provider.url | Requir
#### Overview ####
The JWT federation provider accepts JWT tokens as Bearer tokens within the
Authorization header of the incoming request. Upon successfully extracting and
verifying the token, the request is then processed on behalf of the user
represented by the JWT token.
-This provider is closely related to the Knox Token Service and is essentially
the provider that is used to consume the tokens issued by the Knox Token
Service.
-
-Typical deployments have the KnoxToken service defined in a topology such as
`sandbox.xml` that authenticates users based on username and password which as
with the ShiroProvider. They also have a topology dedicated to clients that
wish to use KnoxTokens to access Hadoop resources through Knox.
+This provider is closely related to the [Knox Token
Service](#KnoxToken+Configuration) and is essentially the provider that is used
to consume the tokens issued by the [Knox Token
Service](#KnoxToken+Configuration).
-The following provider configuration can be used within such a topology.
+Typical deployments have the KnoxToken service defined in a topology that
authenticates users based on username and password with the ShiroProvider. They
also have another topology dedicated to clients that wish to use KnoxTokens to
access Hadoop resources through Knox.
+The following provider configuration can be used with such a topology.
- <provider>
- <role>federation</role>
- <name>JWTProvider</name>
- <enabled>true</enabled>
- <param>
- <name>knox.token.audiences</name>
- <value>tokenbased</value>
- </param>
- </provider>
+ "providers": [
+ {
+ "role": "federation",
+ "name": "JWTProvider",
+ "enabled": "true",
+ "params": {
+ "knox.token.audiences": "tokenbased"
+ }
+ }
+ ]
The `knox.token.audiences` parameter above indicates that any token in an
incoming request must contain an audience claim called "tokenbased". In this
case, the idea is that the issuing KnoxToken service will be configured to
include such an audience claim and that the resulting token is valid to use in
the topology that contains configuration like above. This would generally be
the name of the topology but you can standardize on anything.
@@ -102,5 +107,8 @@ The following table describes the config
Name | Description | Default
---------|-----------|--------
knox.token.audiences | Optional parameter. This parameter allows the
administrator to constrain the use of tokens on this endpoint to those that
have tokens with at least one of the configured audience claims. These claims
have associated configuration within the KnoxToken service as well. This
provides an interesting way to make sure that the token issued based on
authentication to a particular LDAP server or other IdP is accepted but not
others.|N/A
+knox.token.exp.server-managed | Optional parameter for specifying that
server-managed token state should be referenced for evaluating token validity.
| false
+
+The optional `knox.token.exp.server-managed` parameter indicates that Knox is
managing the state of tokens it issues (e.g., expiration) external from the
token, and this external state should be referenced when validating tokens.
This parameter can be ommitted if the global default is configured in
gateway-site (see
[gateway.knox.token.exp.server-managed](#Gateway+Server+Configuration)), and
matches the requirements of this provider. Otherwise, this provider parameter
overrides the gateway configuration for the provider's deployment.
-See the documentation for the Knox Token service for related details.
+See the [documentation for the Knox Token service](#KnoxToken+Configuration)
for related details.
![https://www.pac4j.org/img/logo-knox.png"](https://www.pac4j.org/img/logo-knox.png"){kind=link}