You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by sm...@apache.org on 2023/10/10 08:15:24 UTC

svn commit: r1912852 - in /knox: site/books/knox-2-1-0/ trunk/books/2.1.0/ trunk/books/static/

Author: smolnar
Date: Tue Oct 10 08:15:24 2023
New Revision: 1912852

URL: http://svn.apache.org/viewvc?rev=1912852&view=rev
Log:
KNOX-2965 - Document KNOXSSO Cookie Invalidation

Modified:
    knox/site/books/knox-2-1-0/knoxtokenmanagement_token_management_ui-1.png
    knox/site/books/knox-2-1-0/user-guide.html
    knox/trunk/books/2.1.0/config_knox_sso.md
    knox/trunk/books/2.1.0/config_knox_token.md
    knox/trunk/books/static/knoxtokenmanagement_token_management_ui-1.png

Modified: knox/site/books/knox-2-1-0/knoxtokenmanagement_token_management_ui-1.png
URL: http://svn.apache.org/viewvc/knox/site/books/knox-2-1-0/knoxtokenmanagement_token_management_ui-1.png?rev=1912852&r1=1912851&r2=1912852&view=diff
==============================================================================
Binary files - no diff available.

Modified: knox/site/books/knox-2-1-0/user-guide.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-2-1-0/user-guide.html?rev=1912852&r1=1912851&r2=1912852&view=diff
==============================================================================
--- knox/site/books/knox-2-1-0/user-guide.html (original)
+++ knox/site/books/knox-2-1-0/user-guide.html Tue Oct 10 08:15:24 2023
@@ -5918,6 +5918,14 @@ APACHE_HOME/bin/apachectl -k stop
 <p>The above property holds the KnoxSSO server&rsquo;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="KnoxSSO+Cookie+Invalidation">KnoxSSO Cookie Invalidation</a> <a href="#KnoxSSO+Cookie+Invalidation"><img src="markbook-section-link.png"/></a></h3>
+<p>This feature was implemented in the scope of <a href="https://issues.apache.org/jira/browse/KNOX-2691">KNOX-2691</a>.</p>
+<p>The user story is that there is a need for a new feature that would allow a pre-configured superuser to invalidate previously issued Knox SSO tokens for (a) particular user(s) in case there is a malicious attack in terms of one (or more) of those users&rsquo; SSO tokens got compromised.</p>
+<p>To be able to achieve this goal, the <code>KNOXSSO</code> service is modified in a way such that it saves the generated SSO cookie using Knox&rsquo;s token state service capabilities in case token management is enabled in KNOXSSO&rsquo;s configuration (using the well-known <code>knox.token.exp.server-managed=true</code> parameter, by default this is set to <code>false</code> in the relevant topologies).</p>
+<p>This is only the SSO cookie generation side of the feature. The verification side also needs to be configured the same way: the <code>SSOCookieProvider</code> configuration must have the same parameter to enable this new feature.</p>
+<p>It is very important to highlight, that turning this feature on will make previously initiated <code>KNOX SSO sessions</code> invalid, therefore the browsers must be closed, and/or the cookies have to be removed. This will ensure new user logins which will be captured by the enabled token state service.</p>
+<p>There is another essential configuration when <code>KNOXSSO</code> is configured to use the <a href="#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect">Pac4J federation filter</a>. In this case, the <code>knox.global.logout.page.url</code> configuration is a must-have parameter in <code>gateway-site.xml</code> which usually points to the logout endpoint of the pre-configured SAML/OIDC callback.</p>
+<p>Together with the new <a href="#Token+Management">Token Management UI</a>, pre-configured &ldquo;superusers&rdquo; can disable (invalidate) SSO cookies. This will result in forcing the users to log in again, which, for obvious reasons, the malicious user(s) cannot do.</p>
 <h3><a id="Concurrent+Session+Verification">Concurrent Session Verification</a> <a href="#Concurrent+Session+Verification"><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>This feature allows end-users limiting the number of concurrent UI sessions the users can have. In order to reach this goal the users can be sorted out into three groups: non-privileged, privileged, unlimited.</p>
@@ -6085,10 +6093,10 @@ APACHE_HOME/bin/apachectl -k stop
         &lt;value&gt;false&lt;/value&gt;
     &lt;/param&gt;
 </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>
+<h4><a id="KnoxToken+Renewal,+Revocation+and+Enable/Disable+actions">KnoxToken Renewal, Revocation and Enable/Disable actions</a> <a href="#KnoxToken+Renewal,+Revocation+and+Enable/Disable+actions"><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 &#39;https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/renew&#39;
+<pre><code>curl -ivku admin:admin-password -X PUT -d $TOKEN &#39;https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/renew&#39;
 </code></pre>
 <p>The JSON responses include a flag indicating success or failure.</p>
 <p>A successful result includes the updated expiration time.</p>
@@ -6111,7 +6119,7 @@ APACHE_HOME/bin/apachectl -k stop
 }
 </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 &#39;https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke&#39;
+<pre><code>curl -ivku admin:admin-password -X DELETE -d $TOKEN &#39;https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke&#39;
 </code></pre>
 <p>The JSON responses include a flag indicating success or failure.</p>
 <pre><code>{
@@ -6131,7 +6139,155 @@ APACHE_HOME/bin/apachectl -k stop
   &quot;error&quot;: &quot;Caller (guest) not authorized to revoke tokens.&quot;
 }
 </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>
+<p>KnoxSSO Cookies must not be revoked</p>
+<pre><code>$ curl -iku admin:admin-password  -H &quot;Content-Type: application/json&quot; -d &#39;c236d20c-4a05-4cfa-b35e-2ba6dc451de0&#39; -X DELETE https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke
+HTTP/1.1 403 Forbidden
+Date: Fri, 09 Oct 2023 08:55:25 GMT
+Set-Cookie: KNOXSESSIONID=node03e9y0cy8giy31rh00xc1mrcfx0.node0; Path=/gateway/sandbox; Secure; HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Thu, 05-Oct-2023 08:55:25 GMT; SameSite=lax
+Content-Type: application/json
+Content-Length: 113
+
+{
+  &quot;revoked&quot;: &quot;false&quot;,
+  &quot;error&quot;: &quot;SSO cookie (c236d20c...2ba6dc451de0) cannot not be revoked.&quot;,
+  &quot;code&quot;: 20
+}
+</code></pre>
+<p>Revoke multiple tokens in one batch:</p>
+<pre><code>$ curl -iku admin:admin-password -H &quot;Content-Type: application/json&quot; -d &#39;[&quot;3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2&quot;,&quot;5735f5ae-bddd-4ed1-9383-47a839b9ae2b&quot;]&#39; -X DELETE https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revokeTokens
+HTTP/1.1 200 OK
+Date: Tue, 10 Oct 2023 07:20:39 GMT
+...
+
+{
+  &quot;revoked&quot;: &quot;true&quot;
+}
+</code></pre>
+<p>When revoking multiple tokens, current token state check is executed one by one. This means, if there was at least failed token revocation, the HTTP response will indicate that despite the fact that the rest of the token revocation actions succeeded.</p>
+<h5><a id="Enable">Enable</a> <a href="#Enable"><img src="markbook-section-link.png"/></a></h5>
+<p>This endpoint added in the scope of <a href="https://issues.apache.org/jira/browse/KNOX-2602">KNOX-2602</a>.</p>
+<pre><code>$ curl -ku admin:admin-password -d &quot;1e2f286e-9df1-4123-8d41-e6af523d6923&quot; -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enable
+
+{
+  &quot;setEnabledFlag&quot;: &quot;true&quot;,
+  &quot;isEnabled&quot;: &quot;true&quot;
+}
+</code></pre>
+<p>The JSON responses include a flag (<code>setEnabledFlag</code>) indicating success or failure along with the token state after the action is executed (<code>isEnabled</code>).</p>
+<p>Trying to enable an already enabled token:</p>
+<pre><code>$ curl -ku admin:admin-password -d &quot;1e2f286e-9df1-4123-8d41-e6af523d6923&quot; -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enable
+{
+  &quot;setEnabledFlag&quot;: &quot;false&quot;,
+  &quot;error&quot;: &quot;Token is already enabled&quot;
+}
+</code></pre>
+<p>Disabled KnoxSSO Cookies must not be (re-)enabled:</p>
+<pre><code>$ curl -iku admin:admin-password  -H &quot;Content-Type: application/json&quot; -d &#39;107824ab-c54d-4db3-b3b5-5c964892ad05&#39; -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enable
+HTTP/1.1 400 Bad Request
+Date: Fri, 06 Oct 2023 08:57:58 GMT
+Set-Cookie: KNOXSESSIONID=node011ejmvgcjnlpl13mchqmqjtdjc1.node0; Path=/gateway/sandbox; Secure; HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Thu, 05-Oct-2023 08:57:58 GMT; SameSite=lax
+Content-Type: application/json
+Content-Length: 107
+
+{
+  &quot;setEnabledFlag&quot;: &quot;false&quot;,
+  &quot;error&quot;: &quot;Disabled KnoxSSO Cookies cannot not be enabled&quot;,
+  &quot;code&quot;: 80
+}
+</code></pre>
+<p>Enable multiple tokens in one batch:</p>
+<pre><code>$ curl -iku admin:admin-password -H &quot;Content-Type: application/json&quot; -d &#39;[&quot;3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2&quot;,&quot;5735f5ae-bddd-4ed1-9383-47a839b9ae2b&quot;]&#39; -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enableTokens
+HTTP/1.1 200 OK
+Date: Tue, 10 Oct 2023 07:19:23 GMT
+...
+
+{
+  &quot;setEnabledFlag&quot;: &quot;true&quot;,
+  &quot;isEnabled&quot;: &quot;true&quot;
+}
+</code></pre>
+<p>When enabling multiple tokens, current token state check is not executed. This means, if you are enabling tokens that were already enabled before the batch operation, they remain enabled.</p>
+<h5><a id="Disable">Disable</a> <a href="#Disable"><img src="markbook-section-link.png"/></a></h5>
+<p>This endpoint added in the scope of <a href="https://issues.apache.org/jira/browse/KNOX-2602">KNOX-2602</a>.</p>
+<pre><code>$ curl -ku admin:admin-password -d &quot;1e2f286e-9df1-4123-8d41-e6af523d6923&quot; -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/disable
+{
+  &quot;setEnabledFlag&quot;: &quot;true&quot;,
+  &quot;isEnabled&quot;: &quot;false&quot;
+}
+</code></pre>
+<p>The JSON responses include a flag (<code>setEnabledFlag</code>) indicating success or failure along with the token state after the action is executed (<code>isEnabled</code>).</p>
+<p>Trying to enable an already enabled token:</p>
+<pre><code>$ curl -ku admin:admin-password -d &quot;1e2f286e-9df1-4123-8d41-e6af523d6923&quot; -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/disable
+{
+  &quot;setEnabledFlag&quot;: &quot;false&quot;,
+  &quot;error&quot;: &quot;Token is already disabled&quot;
+}
+</code></pre>
+<p>Disable multiple tokens in one batch:</p>
+<pre><code>$ curl -iku admin:admin-password -H &quot;Content-Type: application/json&quot; -d &#39;[&quot;3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2&quot;,&quot;5735f5ae-bddd-4ed1-9383-47a839b9ae2b&quot;]&#39; -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/disableTokens
+HTTP/1.1 200 OK
+Date: Tue, 10 Oct 2023 07:16:14 GMT
+...
+
+{
+  &quot;setEnabledFlag&quot;: &quot;true&quot;,
+  &quot;isEnabled&quot;: &quot;false&quot;
+}
+</code></pre>
+<p>When disabling multiple tokens, current token state check is not executed. This means, if you are disabling tokens that were already disabled before the batch operation, they remain disabled.</p>
+<h5><a id="Fetching+tokens+for+users">Fetching tokens for users</a> <a href="#Fetching+tokens+for+users"><img src="markbook-section-link.png"/></a></h5>
+<p>Fetching tokens by <code>userName</code>:</p>
+<pre><code>$ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?userName=admin
+HTTP/1.1 200 OK
+Date: Tue, 10 Oct 2023 07:02:32 GMT
+Set-Cookie: KNOXSESSIONID=node01vfrmf5kpjt0ku6mt9765wwx64.node0; Path=/gateway/sandbox; Secure; HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:02:32 GMT; SameSite=lax
+Content-Type: application/json
+Content-Length: 822
+
+{&quot;tokens&quot;:[{&quot;tokenId&quot;:&quot;5244358f-19a3-4834-b16f-aa7ddb2e7fe1&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:03.904+0200&quot;,&quot;expiration&quot;:&quot;2023-10-11T09:02:03.000+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:03.904+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:true,&quot;createdBy&quot;:null,&quot;userName&quot;:&quot;admin&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:null},&quot;issueTimeLong&quot;:1696921323904,&quot;expirationLong&quot;:1697007723000,&quot;maxLifetimeLong&quot;:1697526123904},{&quot;tokenId&quot;:&quot;9b37e838-4aa2-43fd-b2f1-b35660b33778&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:14.271+0200&quot;,&quot;expiration&quot;:&quot;2023-10-10T10:02:14.242+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:14.271+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:false,&quot;createdBy&quot;:null,&quot;userN
 ame&quot;:&quot;admin&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:&quot;admin token 1&quot;},&quot;issueTimeLong&quot;:1696921334271,&quot;expirationLong&quot;:1696924934242,&quot;maxLifetimeLong&quot;:1697526134271}]}
+</code></pre>
+<p>Fetching tokens by <code>createdBy</code>:</p>
+<pre><code>$ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?createdBy=admin
+HTTP/1.1 200 OK
+Date: Tue, 10 Oct 2023 07:05:45 GMT
+Set-Cookie: KNOXSESSIONID=node047nn0zjkauc41qzexnjmlhj2j6.node0; Path=/gateway/sandbox; Secure; HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:05:46 GMT; SameSite=lax
+Content-Type: application/json
+Content-Length: 436
+
+{&quot;tokens&quot;:[{&quot;tokenId&quot;:&quot;3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:29.146+0200&quot;,&quot;expiration&quot;:&quot;2023-10-10T10:02:29.127+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:29.146+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:false,&quot;createdBy&quot;:&quot;admin&quot;,&quot;userName&quot;:&quot;guest&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:&quot;admin token 1 for guest&quot;},&quot;issueTimeLong&quot;:1696921349146,&quot;expirationLong&quot;:1696924949127,&quot;maxLifetimeLong&quot;:1697526149146}]}
+</code></pre>
+<p>Fetching tokens by <code>userNameOrCreatedBy</code>:</p>
+<pre><code>$ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?userNameOrCreatedBy=admin
+HTTP/1.1 200 OK
+Date: Tue, 10 Oct 2023 07:07:02 GMT
+Set-Cookie: KNOXSESSIONID=node0rt50pq4getaj1s1owcj3pvgfm7.node0; Path=/gateway/sandbox; Secure; HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:07:02 GMT; SameSite=lax
+Content-Type: application/json
+Content-Length: 1246
+
+{&quot;tokens&quot;:[{&quot;tokenId&quot;:&quot;5244358f-19a3-4834-b16f-aa7ddb2e7fe1&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:03.904+0200&quot;,&quot;expiration&quot;:&quot;2023-10-11T09:02:03.000+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:03.904+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:true,&quot;createdBy&quot;:null,&quot;userName&quot;:&quot;admin&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:null},&quot;issueTimeLong&quot;:1696921323904,&quot;expirationLong&quot;:1697007723000,&quot;maxLifetimeLong&quot;:1697526123904},{&quot;tokenId&quot;:&quot;9b37e838-4aa2-43fd-b2f1-b35660b33778&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:14.271+0200&quot;,&quot;expiration&quot;:&quot;2023-10-10T10:02:14.242+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:14.271+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:false,&quot;createdBy&quot;:null,&quot;userN
 ame&quot;:&quot;admin&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:&quot;admin token 1&quot;},&quot;issueTimeLong&quot;:1696921334271,&quot;expirationLong&quot;:1696924934242,&quot;maxLifetimeLong&quot;:1697526134271},{&quot;tokenId&quot;:&quot;3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:29.146+0200&quot;,&quot;expiration&quot;:&quot;2023-10-10T10:02:29.127+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:29.146+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:false,&quot;createdBy&quot;:&quot;admin&quot;,&quot;userName&quot;:&quot;guest&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:&quot;admin token 1 for guest&quot;},&quot;issueTimeLong&quot;:1696921349146,&quot;expirationLong&quot;:1696924949127,&quot;maxLifetimeLong&quot;:1697526149146}]}
+</code></pre>
+<p>Fetching <code>all</code> tokens:</p>
+<pre><code>$ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?allTokens=true
+HTTP/1.1 200 OK
+Date: Tue, 10 Oct 2023 07:08:08 GMT
+Set-Cookie: KNOXSESSIONID=node0fctcnhp9fm3w1gq1mc2z993109.node0; Path=/gateway/sandbox; Secure; HttpOnly
+Expires: Thu, 01 Jan 1970 00:00:00 GMT
+Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:08:08 GMT; SameSite=lax
+Content-Type: application/json
+Content-Length: 2048
+
+{&quot;tokens&quot;:[{&quot;tokenId&quot;:&quot;5244358f-19a3-4834-b16f-aa7ddb2e7fe1&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:03.904+0200&quot;,&quot;expiration&quot;:&quot;2023-10-11T09:02:03.000+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:03.904+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:true,&quot;createdBy&quot;:null,&quot;userName&quot;:&quot;admin&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:null},&quot;issueTimeLong&quot;:1696921323904,&quot;expirationLong&quot;:1697007723000,&quot;maxLifetimeLong&quot;:1697526123904},{&quot;tokenId&quot;:&quot;9b37e838-4aa2-43fd-b2f1-b35660b33778&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:14.271+0200&quot;,&quot;expiration&quot;:&quot;2023-10-10T10:02:14.242+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:14.271+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:false,&quot;createdBy&quot;:null,&quot;userN
 ame&quot;:&quot;admin&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:&quot;admin token 1&quot;},&quot;issueTimeLong&quot;:1696921334271,&quot;expirationLong&quot;:1696924934242,&quot;maxLifetimeLong&quot;:1697526134271},{&quot;tokenId&quot;:&quot;3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:02:29.146+0200&quot;,&quot;expiration&quot;:&quot;2023-10-10T10:02:29.127+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:02:29.146+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:false,&quot;createdBy&quot;:&quot;admin&quot;,&quot;userName&quot;:&quot;guest&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:&quot;admin token 1 for guest&quot;},&quot;issueTimeLong&quot;:1696921349146,&quot;expirationLong&quot;:1696924949127,&quot;maxLifetimeLong&quot;:1697526149146},{&quot;tokenId&quot;:&quot;75f1b921-680d-433d-976f-270a100a1cf9&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:07:50.871+0200&quot;,&quot;
 expiration&quot;:&quot;2023-10-11T09:07:50.000+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:07:50.871+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:true,&quot;createdBy&quot;:null,&quot;userName&quot;:&quot;sam&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:null},&quot;issueTimeLong&quot;:1696921670871,&quot;expirationLong&quot;:1697008070000,&quot;maxLifetimeLong&quot;:1697526470871},{&quot;tokenId&quot;:&quot;5735f5ae-bddd-4ed1-9383-47a839b9ae2b&quot;,&quot;issueTime&quot;:&quot;2023-10-10T09:07:55.293+0200&quot;,&quot;expiration&quot;:&quot;2023-10-10T10:07:55.276+0200&quot;,&quot;maxLifetime&quot;:&quot;2023-10-17T09:07:55.293+0200&quot;,&quot;metadata&quot;:{&quot;customMetadataMap&quot;:{},&quot;knoxSsoCookie&quot;:false,&quot;createdBy&quot;:null,&quot;userName&quot;:&quot;sam&quot;,&quot;enabled&quot;:true,&quot;comment&quot;:&quot;sam token&quot;},&quot;issueTimeLong&quot;:1696921675293,&quot;expirationLong&quot;:1
 696925275276,&quot;maxLifetimeLong&quot;:1697526475293}]}
+</code></pre>
 <h4><a id="Token+Generation/Management+UIs">Token Generation/Management UIs</a> <a href="#Token+Generation/Management+UIs"><img src="markbook-section-link.png"/></a></h4>
 <h5><a id="Overview">Overview</a> <a href="#Overview"><img src="markbook-section-link.png"/></a></h5>
 <p>In Apache Knox v2.0.0 the team added two new UIs that are directly accessible from the Knox Home page:</p>
@@ -6253,19 +6409,54 @@ APACHE_HOME/bin/apachectl -k stop
 </ul>
 <p>The default value is <code>RETURN_ERROR</code>.</p>
 <h5><a id="Token+Management">Token Management</a> <a href="#Token+Management"><img src="markbook-section-link.png"/></a></h5>
-<p>In addition to the token generation UI, Knox comes with a Token Management UI where logged-in users can see all the active tokens that they generated before. That is, if a token got expired and was removed from the underlying token store, it won&rsquo;t be displayed here.</p>
+<p>In addition to the token generation UI, Knox comes with the Token Management UI where logged-in users can see all the active tokens that were generated before. That is, if a token got expired and was removed from the underlying token store, it won&rsquo;t be displayed here. Based on a configuration you can find below, users can see only their tokens or all of them.</p>
 <p><img src="knoxtokenmanagement_token_management_ui-1.png" /></p>
-<p>On this page, you will see two different tables:</p>
-<ol>
-  <li>tokens of the logged-in user</li>
-  <li>tokens the logged-in user generated for other users</li>
-</ol>
-<p>Both tables display basic information about the generated token(s). In the first one end-users can execute the following actions:</p>
+<p>On this page, you will a table with the following information:</p>
 <ol>
-  <li>Enable/Disable - based on the current status, you can temporarily enable/disable a token. Please note that disabled tokens are not allowed to use for authentication purposes.</li>
-  <li>Revoke - you can remove the token from the persistent store. Please note this action cannot be undone, once you revoked a token Knox will delete it from the in-memory cache as well as the underlying persistent token storage</li>
+  <li>Each row starts with a selection checkbox for batch operations (except for disabled KnoxSSO cookies, as there is no point in doing anything with them)</li>
+  <li>A unique token identifer. Disabled token&rsquo;s Token ID value is shown in orange</li>
+  <li>Information on when the token was created and when it will expire
+    <ol>
+      <li>if the token is already expired, the expiration time is shown in red</li>
+      <li>if the token is still valid, the expiration time is shown in green</li>
+    </ol>
+  </li>
+  <li>Username indicates the user for whom the token is created for</li>
+  <li>Impersonated is a boolean flag indicating if this is an impersonated token:
+    <ol>
+      <li>green check: yes, this is impersonated. You&rsquo;ll see the user who created the token under the icon</li>
+      <li>red cross: no, this is not an impersonated token</li>
+    </ol>
+  </li>
+  <li>KnoxSSO is another boolean flag that indicates if this token is created by the <code>KNOXSSO</code> service if the feature was enabled
+    <ol>
+      <li>green check: yes, this is KnoxSSO cookie (token)</li>
+      <li>red cross: no, this is not a KnoxSSO cookie (it was created by a regular token API call or on the Token Generation page)</li>
+    </ol>
+  </li>
+  <li>In the Actions column you will see
+    <ol>
+      <li>the enable/disable/revoke actions are visible for impersonated tokens too</li>
+      <li>KnoxSSO cookies cannot be revoked nor re-enabled</li>
+    </ol>
+  </li>
 </ol>
 <p>In order to refresh the table, you can use the <code>Refresh icon</code> above the table (if you generated tokens on another tab for instance).</p>
+<p><strong>Batch operations</strong></p>
+<p>When at least one token is selected, the following buttons are shown under the table:  - Disable Selected Tokens: when executed, all the selected tokens become disabled (if they were disabled originally, they will remain disabled)  - Enable Selected Tokens: when executed, all the selected tokens become enabled (if they were enabled originally, they will remain enabled)  - Revoke Selected Tokens: when executed, all the selected tokens will be revoked. Please note this option is shown only, if there is no KnoxSSO cookie (token) selected (i.e. batch revocation only works with regular tokens).</p>
+<p><strong>Toggles</strong></p>
+<ul>
+  <li><code>Show Disabled KnoxSSO Cookies</code>: this is true by default. Since disabled KnoxSSO cookies remain in the underlying token state service until they expire, it may bother users to see them in the tokens table. Flipping this toggle button helps to hide them.</li>
+  <li><code>Show My Tokens Only</code>: this toggle button is only visible to users, who can see all tokens. By default, this is false. Enabling it will filter the tokens table in a way such that it will contain tokens only that were generated for the logged in user (impersonated or not).</li>
+</ul>
+<p><strong>Configuration</strong></p>
+<p>By default, logged in users can see token that were generated by them or for them (in caase of token impersonation). However, you may want to edit the <code>gateway.knox.token.management.users.can.see.all.tokens</code> parameter in <code>gateway-site.xml</code> to allow other users than <code>admin</code> to become such a &ldquo;superuser&rdquo;, who can see all tokens on the Token Management UI.</p>
+<pre><code> &lt;property&gt;
+    &lt;name&gt;gateway.knox.token.management.users.can.see.all.tokens&lt;/name&gt;
+    &lt;value&gt;admin&lt;/value&gt;
+    &lt;description&gt;A comma-separated list of user names who can see all tokens on the Token Management page&lt;/description&gt;
+&lt;/property&gt;
+</code></pre>
 <h5><a id="Token+impersonation">Token impersonation</a> <a href="#Token+impersonation"><img src="markbook-section-link.png"/></a></h5>
 <p>On the token generation page end-users can generate tokens on behalf of other users by specifying the desired user name in the token <code>impersonation</code> field. The following screenshot sows a successful token generation for user <code>tom</code> (the logged in user is <code>admin</code>).</p>
 <p><img src="knoxtokenmanagement_token_generation_ui-successful-doas.png" /></p>

Modified: knox/trunk/books/2.1.0/config_knox_sso.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_knox_sso.md?rev=1912852&r1=1912851&r2=1912852&view=diff
==============================================================================
--- knox/trunk/books/2.1.0/config_knox_sso.md (original)
+++ knox/trunk/books/2.1.0/config_knox_sso.md Tue Oct 10 08:15:24 2023
@@ -152,6 +152,22 @@ Individual UIs within the Hadoop ecosyst
 
 Blogs will be provided on the Apache Knox project site for these usecases as they become available.
 
+### KnoxSSO Cookie Invalidation
+
+This feature was implemented in the scope of [KNOX-2691](https://issues.apache.org/jira/browse/KNOX-2691).
+
+The user story is that there is a need for a new feature that would allow a pre-configured superuser to invalidate previously issued Knox SSO tokens for (a) particular user(s) in case there is a malicious attack in terms of one (or more) of those users' SSO tokens got compromised.
+
+To be able to achieve this goal, the `KNOXSSO` service is modified in a way such that it saves the generated SSO cookie using Knox's token state service capabilities in case token management is enabled in KNOXSSO's configuration (using the well-known `knox.token.exp.server-managed=true` parameter, by default this is set to `false` in the relevant topologies).
+
+This is only the SSO cookie generation side of the feature. The verification side also needs to be configured the same way: the `SSOCookieProvider` configuration must have the same parameter to enable this new feature.
+
+It is very important to highlight, that turning this feature on will make previously initiated `KNOX SSO sessions` invalid, therefore the browsers must be closed, and/or the cookies have to be removed. This will ensure new user logins which will be captured by the enabled token state service.
+
+There is another essential configuration when `KNOXSSO` is configured to use the [Pac4J federation filter](#Pac4j+Provider+-+CAS+/+OAuth+/+SAML+/+OpenID+Connect). In this case, the `knox.global.logout.page.url` configuration is a must-have parameter in `gateway-site.xml` which usually points to the logout endpoint of the pre-configured SAML/OIDC callback.
+
+Together with the new [Token Management UI](#Token+Management), pre-configured "superusers" can disable (invalidate) SSO cookies. This will result in forcing the users to log in again, which, for obvious reasons, the malicious user(s) cannot do.
+
 ### Concurrent Session Verification
 
 #### Overview

Modified: knox/trunk/books/2.1.0/config_knox_token.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_knox_token.md?rev=1912852&r1=1912851&r2=1912852&view=diff
==============================================================================
--- knox/trunk/books/2.1.0/config_knox_token.md (original)
+++ knox/trunk/books/2.1.0/config_knox_token.md Tue Oct 10 08:15:24 2023
@@ -83,14 +83,14 @@ This feature is enabled by default. If y
             <value>false</value>
         </param>
 
-#### KnoxToken Renewal and Revocation
+#### KnoxToken Renewal, Revocation and Enable/Disable actions
 
 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'
+    curl -ivku admin:admin-password -X PUT -d $TOKEN 'https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/renew'
 
 The JSON responses include a flag indicating success or failure.
 
@@ -119,7 +119,7 @@ Unauthorized caller
 
 ##### Revocation
 
-    curl -ivku admin:admin-password -X POST -d $TOKEN 'https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke'
+    curl -ivku admin:admin-password -X DELETE -d $TOKEN 'https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke'
 
 The JSON responses include a flag indicating success or failure.
 
@@ -143,8 +143,172 @@ Unauthorized caller
 	  "error": "Caller (guest) not authorized to revoke tokens."
 	}
 
+KnoxSSO Cookies must not be revoked
+
+    $ curl -iku admin:admin-password  -H "Content-Type: application/json" -d 'c236d20c-4a05-4cfa-b35e-2ba6dc451de0' -X DELETE https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revoke
+    HTTP/1.1 403 Forbidden
+    Date: Fri, 09 Oct 2023 08:55:25 GMT
+    Set-Cookie: KNOXSESSIONID=node03e9y0cy8giy31rh00xc1mrcfx0.node0; Path=/gateway/sandbox; Secure; HttpOnly
+    Expires: Thu, 01 Jan 1970 00:00:00 GMT
+    Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Thu, 05-Oct-2023 08:55:25 GMT; SameSite=lax
+    Content-Type: application/json
+    Content-Length: 113
+
+    {
+      "revoked": "false",
+      "error": "SSO cookie (c236d20c...2ba6dc451de0) cannot not be revoked.",
+      "code": 20
+    }
+
+Revoke multiple tokens in one batch:
+
+    $ curl -iku admin:admin-password -H "Content-Type: application/json" -d '["3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2","5735f5ae-bddd-4ed1-9383-47a839b9ae2b"]' -X DELETE https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/revokeTokens
+    HTTP/1.1 200 OK
+    Date: Tue, 10 Oct 2023 07:20:39 GMT
+    ...
+
+    {
+      "revoked": "true"
+    }
+    
+When revoking multiple tokens, current token state check is executed one by one. This means, if there was at least failed token revocation, the HTTP response will indicate that despite the fact that the rest of the token revocation actions succeeded.
+
+##### Enable
+
+This endpoint added in the scope of [KNOX-2602](https://issues.apache.org/jira/browse/KNOX-2602).
+
+    $ curl -ku admin:admin-password -d "1e2f286e-9df1-4123-8d41-e6af523d6923" -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enable
+    
+    {
+      "setEnabledFlag": "true",
+      "isEnabled": "true"
+    }
+The JSON responses include a flag (`setEnabledFlag`) indicating success or failure along with the token state after the action is executed (`isEnabled`).
+
+Trying to enable an already enabled token:
+
+    $ curl -ku admin:admin-password -d "1e2f286e-9df1-4123-8d41-e6af523d6923" -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enable
+    {
+      "setEnabledFlag": "false",
+      "error": "Token is already enabled"
+    }
+
+Disabled KnoxSSO Cookies must not be (re-)enabled:
+
+    $ curl -iku admin:admin-password  -H "Content-Type: application/json" -d '107824ab-c54d-4db3-b3b5-5c964892ad05' -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enable
+    HTTP/1.1 400 Bad Request
+    Date: Fri, 06 Oct 2023 08:57:58 GMT
+    Set-Cookie: KNOXSESSIONID=node011ejmvgcjnlpl13mchqmqjtdjc1.node0; Path=/gateway/sandbox; Secure; HttpOnly
+    Expires: Thu, 01 Jan 1970 00:00:00 GMT
+    Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Thu, 05-Oct-2023 08:57:58 GMT; SameSite=lax
+    Content-Type: application/json
+    Content-Length: 107
+    
+    {
+      "setEnabledFlag": "false",
+      "error": "Disabled KnoxSSO Cookies cannot not be enabled",
+      "code": 80
+    }
+
+Enable multiple tokens in one batch:
+
+    $ curl -iku admin:admin-password -H "Content-Type: application/json" -d '["3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2","5735f5ae-bddd-4ed1-9383-47a839b9ae2b"]' -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/enableTokens
+    HTTP/1.1 200 OK
+    Date: Tue, 10 Oct 2023 07:19:23 GMT
+    ...
+
+    {
+      "setEnabledFlag": "true",
+      "isEnabled": "true"
+    }
+When enabling multiple tokens, current token state check is not executed. This means, if you are enabling tokens that were already enabled before the batch operation, they remain enabled.
+
+##### Disable
+
+This endpoint added in the scope of [KNOX-2602](https://issues.apache.org/jira/browse/KNOX-2602).
+
+    $ curl -ku admin:admin-password -d "1e2f286e-9df1-4123-8d41-e6af523d6923" -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/disable
+    {
+      "setEnabledFlag": "true",
+      "isEnabled": "false"
+    }
+The JSON responses include a flag (`setEnabledFlag`) indicating success or failure along with the token state after the action is executed (`isEnabled`).
+
+Trying to enable an already enabled token:
+
+    $ curl -ku admin:admin-password -d "1e2f286e-9df1-4123-8d41-e6af523d6923" -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/disable
+    {
+      "setEnabledFlag": "false",
+      "error": "Token is already disabled"
+    }
+
+Disable multiple tokens in one batch:
+
+    $ curl -iku admin:admin-password -H "Content-Type: application/json" -d '["3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2","5735f5ae-bddd-4ed1-9383-47a839b9ae2b"]' -X PUT https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/disableTokens
+    HTTP/1.1 200 OK
+    Date: Tue, 10 Oct 2023 07:16:14 GMT
+    ...
+
+    {
+      "setEnabledFlag": "true",
+      "isEnabled": "false"
+    }
+When disabling multiple tokens, current token state check is not executed. This means, if you are disabling tokens that were already disabled before the batch operation, they remain disabled.
+
+##### Fetching tokens for users
+
+Fetching tokens by `userName`:
+
+    $ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?userName=admin
+    HTTP/1.1 200 OK
+    Date: Tue, 10 Oct 2023 07:02:32 GMT
+    Set-Cookie: KNOXSESSIONID=node01vfrmf5kpjt0ku6mt9765wwx64.node0; Path=/gateway/sandbox; Secure; HttpOnly
+    Expires: Thu, 01 Jan 1970 00:00:00 GMT
+    Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:02:32 GMT; SameSite=lax
+    Content-Type: application/json
+    Content-Length: 822
+
+    {"tokens":[{"tokenId":"5244358f-19a3-4834-b16f-aa7ddb2e7fe1","issueTime":"2023-10-10T09:02:03.904+0200","expiration":"2023-10-11T09:02:03.000+0200","maxLifetime":"2023-10-17T09:02:03.904+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":true,"createdBy":null,"userName":"admin","enabled":true,"comment":null},"issueTimeLong":1696921323904,"expirationLong":1697007723000,"maxLifetimeLong":1697526123904},{"tokenId":"9b37e838-4aa2-43fd-b2f1-b35660b33778","issueTime":"2023-10-10T09:02:14.271+0200","expiration":"2023-10-10T10:02:14.242+0200","maxLifetime":"2023-10-17T09:02:14.271+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":false,"createdBy":null,"userName":"admin","enabled":true,"comment":"admin token 1"},"issueTimeLong":1696921334271,"expirationLong":1696924934242,"maxLifetimeLong":1697526134271}]}
+
+Fetching tokens by `createdBy`:
+
+    $ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?createdBy=admin
+    HTTP/1.1 200 OK
+    Date: Tue, 10 Oct 2023 07:05:45 GMT
+    Set-Cookie: KNOXSESSIONID=node047nn0zjkauc41qzexnjmlhj2j6.node0; Path=/gateway/sandbox; Secure; HttpOnly
+    Expires: Thu, 01 Jan 1970 00:00:00 GMT
+    Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:05:46 GMT; SameSite=lax
+    Content-Type: application/json
+    Content-Length: 436
+
+    {"tokens":[{"tokenId":"3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2","issueTime":"2023-10-10T09:02:29.146+0200","expiration":"2023-10-10T10:02:29.127+0200","maxLifetime":"2023-10-17T09:02:29.146+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":false,"createdBy":"admin","userName":"guest","enabled":true,"comment":"admin token 1 for guest"},"issueTimeLong":1696921349146,"expirationLong":1696924949127,"maxLifetimeLong":1697526149146}]}
+
+Fetching tokens by `userNameOrCreatedBy`:
+
+    $ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?userNameOrCreatedBy=admin
+    HTTP/1.1 200 OK
+    Date: Tue, 10 Oct 2023 07:07:02 GMT
+    Set-Cookie: KNOXSESSIONID=node0rt50pq4getaj1s1owcj3pvgfm7.node0; Path=/gateway/sandbox; Secure; HttpOnly
+    Expires: Thu, 01 Jan 1970 00:00:00 GMT
+    Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:07:02 GMT; SameSite=lax
+    Content-Type: application/json
+    Content-Length: 1246
+
+    {"tokens":[{"tokenId":"5244358f-19a3-4834-b16f-aa7ddb2e7fe1","issueTime":"2023-10-10T09:02:03.904+0200","expiration":"2023-10-11T09:02:03.000+0200","maxLifetime":"2023-10-17T09:02:03.904+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":true,"createdBy":null,"userName":"admin","enabled":true,"comment":null},"issueTimeLong":1696921323904,"expirationLong":1697007723000,"maxLifetimeLong":1697526123904},{"tokenId":"9b37e838-4aa2-43fd-b2f1-b35660b33778","issueTime":"2023-10-10T09:02:14.271+0200","expiration":"2023-10-10T10:02:14.242+0200","maxLifetime":"2023-10-17T09:02:14.271+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":false,"createdBy":null,"userName":"admin","enabled":true,"comment":"admin token 1"},"issueTimeLong":1696921334271,"expirationLong":1696924934242,"maxLifetimeLong":1697526134271},{"tokenId":"3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2","issueTime":"2023-10-10T09:02:29.146+0200","expiration":"2023-10-10T10:02:29.127+0200","maxLifetime":"2023-10-17T09:02:29.
 146+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":false,"createdBy":"admin","userName":"guest","enabled":true,"comment":"admin token 1 for guest"},"issueTimeLong":1696921349146,"expirationLong":1696924949127,"maxLifetimeLong":1697526149146}]}
+
+Fetching `all` tokens:
+
+    $ curl -iku admin:admin-password -X GET https://localhost:8443/gateway/sandbox/knoxtoken/api/v1/token/getUserTokens?allTokens=true
+    HTTP/1.1 200 OK
+    Date: Tue, 10 Oct 2023 07:08:08 GMT
+    Set-Cookie: KNOXSESSIONID=node0fctcnhp9fm3w1gq1mc2z993109.node0; Path=/gateway/sandbox; Secure; HttpOnly
+    Expires: Thu, 01 Jan 1970 00:00:00 GMT
+    Set-Cookie: rememberMe=deleteMe; Path=/gateway/sandbox; Max-Age=0; Expires=Mon, 09-Oct-2023 07:08:08 GMT; SameSite=lax
+    Content-Type: application/json
+    Content-Length: 2048
+
+    {"tokens":[{"tokenId":"5244358f-19a3-4834-b16f-aa7ddb2e7fe1","issueTime":"2023-10-10T09:02:03.904+0200","expiration":"2023-10-11T09:02:03.000+0200","maxLifetime":"2023-10-17T09:02:03.904+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":true,"createdBy":null,"userName":"admin","enabled":true,"comment":null},"issueTimeLong":1696921323904,"expirationLong":1697007723000,"maxLifetimeLong":1697526123904},{"tokenId":"9b37e838-4aa2-43fd-b2f1-b35660b33778","issueTime":"2023-10-10T09:02:14.271+0200","expiration":"2023-10-10T10:02:14.242+0200","maxLifetime":"2023-10-17T09:02:14.271+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":false,"createdBy":null,"userName":"admin","enabled":true,"comment":"admin token 1"},"issueTimeLong":1696921334271,"expirationLong":1696924934242,"maxLifetimeLong":1697526134271},{"tokenId":"3c043de7-f9e9-4c1a-b32f-abfbc3dcbcb2","issueTime":"2023-10-10T09:02:29.146+0200","expiration":"2023-10-10T10:02:29.127+0200","maxLifetime":"2023-10-17T09:02:29.
 146+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":false,"createdBy":"admin","userName":"guest","enabled":true,"comment":"admin token 1 for guest"},"issueTimeLong":1696921349146,"expirationLong":1696924949127,"maxLifetimeLong":1697526149146},{"tokenId":"75f1b921-680d-433d-976f-270a100a1cf9","issueTime":"2023-10-10T09:07:50.871+0200","expiration":"2023-10-11T09:07:50.000+0200","maxLifetime":"2023-10-17T09:07:50.871+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":true,"createdBy":null,"userName":"sam","enabled":true,"comment":null},"issueTimeLong":1696921670871,"expirationLong":1697008070000,"maxLifetimeLong":1697526470871},{"tokenId":"5735f5ae-bddd-4ed1-9383-47a839b9ae2b","issueTime":"2023-10-10T09:07:55.293+0200","expiration":"2023-10-10T10:07:55.276+0200","maxLifetime":"2023-10-17T09:07:55.293+0200","metadata":{"customMetadataMap":{},"knoxSsoCookie":false,"createdBy":null,"userName":"sam","enabled":true,"comment":"sam token"},"issueTimeLong":1696921675293,"expira
 tionLong":1696925275276,"maxLifetimeLong":1697526475293}]}
 
-See documentation in Client Details for KnoxShell init, list and destroy for commands that leverage this token service for CLI sessions.
 
 #### Token Generation/Management UIs
 
@@ -298,21 +462,51 @@ The default value is `RETURN_ERROR`.
 
 ##### Token Management
 
-In addition to the token generation UI, Knox comes with a Token Management UI where logged-in users can see all the active tokens that they generated before. That is, if a token got expired and was removed from the underlying token store, it won't be displayed here.
+In addition to the token generation UI, Knox comes with the Token Management UI where logged-in users can see all the active tokens that were generated before. That is, if a token got expired and was removed from the underlying token store, it won't be displayed here. Based on a configuration you can find below, users can see only their tokens or all of them.
 
  ![](knoxtokenmanagement_token_management_ui-1.png)
 
-On this page, you will see two different tables:
+On this page, you will a table with the following information:
 
-1. tokens of the logged-in user
-2. tokens the logged-in user generated for other users
+1. Each row starts with a selection checkbox for batch operations (except for disabled KnoxSSO cookies, as there is no point in doing anything with them)
+2. A unique token identifer. Disabled token's Token ID value is shown in orange
+3. Information on when the token was created and when it will expire
+    1. if the token is already expired, the expiration time is shown in red
+    2. if the token is still valid, the expiration time is shown in green
+4. Username indicates the user for whom the token is created for
+5. Impersonated is a boolean flag indicating if this is an impersonated token:
+    1. green check: yes, this is impersonated. You'll see the user who created the token under the icon
+    2. red cross: no, this is not an impersonated token
+6. KnoxSSO is another boolean flag that indicates if this token is created by the `KNOXSSO` service if the feature was enabled
+    1. green check: yes, this is KnoxSSO cookie (token)
+    2. red cross: no, this is not a KnoxSSO cookie (it was created by a regular token API call or on the Token Generation page)
+7. In the Actions column you will see
+    1. the enable/disable/revoke actions are visible for impersonated tokens too
+    2. KnoxSSO cookies cannot be revoked nor re-enabled
 
-Both tables display basic information about the generated token(s). In the first one end-users can execute the following actions:
+In order to refresh the table, you can use the `Refresh icon` above the table (if you generated tokens on another tab for instance).
 
-1.  Enable/Disable - based on the current status, you can temporarily enable/disable a token. Please note that disabled tokens are not allowed to use for authentication purposes.
-2.  Revoke - you can remove the token from the persistent store. Please note this action cannot be undone, once you revoked a token Knox will delete it from the in-memory cache as well as the underlying persistent token storage
+**Batch operations**
 
-In order to refresh the table, you can use the `Refresh icon` above the table (if you generated tokens on another tab for instance).
+When at least one token is selected, the following buttons are shown under the table:
+    - Disable Selected Tokens: when executed, all the selected tokens become disabled (if they were disabled originally, they will remain disabled)
+    - Enable Selected Tokens: when executed, all the selected tokens become enabled (if they were enabled originally, they will remain enabled)
+    - Revoke Selected Tokens: when executed, all the selected tokens will be revoked. Please note this option is shown only, if there is no KnoxSSO cookie (token) selected (i.e. batch revocation only works with regular tokens).
+
+**Toggles**
+
+- `Show Disabled KnoxSSO Cookies`: this is true by default. Since disabled KnoxSSO cookies remain in the underlying token state service until they expire, it may bother users to see them in the tokens table. Flipping this toggle button helps to hide them.
+- `Show My Tokens Only`: this toggle button is only visible to users, who can see all tokens. By default, this is false. Enabling it will filter the tokens table in a way such that it will contain tokens only that were generated for the logged in user (impersonated or not).
+
+**Configuration**
+
+By default, logged in users can see token that were generated by them or for them (in caase of token impersonation). However, you may want to edit the `gateway.knox.token.management.users.can.see.all.tokens` parameter in `gateway-site.xml` to allow other users than `admin` to become such a "superuser", who can see all tokens on the Token Management UI.
+
+     <property>
+        <name>gateway.knox.token.management.users.can.see.all.tokens</name>
+        <value>admin</value>
+        <description>A comma-separated list of user names who can see all tokens on the Token Management page</description>
+    </property>
 
 ##### Token impersonation
 

Modified: knox/trunk/books/static/knoxtokenmanagement_token_management_ui-1.png
URL: http://svn.apache.org/viewvc/knox/trunk/books/static/knoxtokenmanagement_token_management_ui-1.png?rev=1912852&r1=1912851&r2=1912852&view=diff
==============================================================================
Binary files - no diff available.