Author: smolnar
Date: Fri Dec 23 10:54:33 2022
New Revision: 1906185
URL: http://svn.apache.org/viewvc?rev=1906185&view=rev
Log:
KNOX-2856 - Document changes in KNOX-2839
Modified:
knox/site/books/knox-2-0-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/2.0.0/config_id_assertion.md
knox/trunk/books/2.0.0/config_knox_token.md
Modified: knox/site/books/knox-2-0-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-2-0-0/user-guide.html?rev=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/site/books/knox-2-0-0/user-guide.html (original)
+++ knox/site/books/knox-2-0-0/user-guide.html Fri Dec 23 10:54:33 2022
@@ -3986,6 +3986,22 @@ session required pam_env.so user_
<name>group.principal.mapping</name>
<value>*=users;hdfs=admin</value>
</param>
+ <param>
+ <name>hadoop.proxyuser.impersonation.enabled</name>
+ <value>false</value>
+ </param>
+ <param>
+ <name>hadoop.proxyuser.admin.users</name>
+ <value>*</value>
+ </param>
+ <param>
+ <name>hadoop.proxyuser.admin.groups</name>
+ <value>*</value>
+ </param>
+ <param>
+ <name>hadoop.proxyuser.admin.hosts</name>
+ <value>*</value>
+ </param>
</provider>
</code></pre>
<p>This configuration identifies the same identity assertion provider but does
provide principal and group mapping rules. In this case, when a user is
authenticated as “guest” his identity is actually asserted to the
Hadoop cluster as “hdfs”. In addition, since there are group
principal mappings defined, he will also be considered as a member of the
groups “users” and “admin”. In this particular example
the wildcard "*“ is used to indicate that all authenticated users
need to be considered members of the ”users“ group and that only
the user ”hdfs“ is mapped to be a member of the ”admin"
group.</p>
@@ -3994,6 +4010,27 @@ session required pam_env.so user_
<p>This feature allows us to map the authenticated principal to a runAs or
impersonated principal to be asserted to the Hadoop services in the backend.</p>
<p>When a principal mapping is defined that results in an impersonated
principal, this impersonated principal is then the effective principal.</p>
<p>If there is no mapping to another principal then the authenticated or
primary principal is the effective principal.</p>
+<p>Another way to impersonate principals is to apply Hadoop Proxyuser-based
impersonations as described in the next section.</p>
+<h5><a id="Hadoop+Proxyuser+impersonation">Hadoop Proxyuser impersonation</a>
<a href="#Hadoop+Proxyuser+impersonation"><img
src="markbook-section-link.png"/></a></h5>
+<p>From v2.0.0, an authenticated user can impersonate other user(s) leveraging
Hadoop’s proxuyser configuration mechanism. This feature was implemented
in <a href="https://issues.apache.org/jira/browse/KNOX-2839";>KNOX-2839</a> and
requires the following configuration to work:</p>
+<ul>
+ <li><code>hadoop.proxyuser.impersonation.enabled</code> - a
<code>boolean</code> flag indicates if token impersonation is enabled. Defaults
to <code>true</code></li>
+ <li><code>hadoop.proxyuser.$username.users</code> - indicates the list of
users for whom <code>$username</code> is allowed to impersonate. It is possible
to set this to a 1-element list using the <code>*</code> wildcard which means
<code>$username</code> can impersonate everyone. Defaults to an empty list that
is equivalent to <code>$username</code> is not allowed to impersonate
anyone.</li>
+ <li><code>hadoop.proxyuser.$username.groups</code> - indicates the list of
group names for whose members <code>$username</code> is allowed to impersonate.
It is possible to set this to a 1-element list using the <code>*</code>
wildcard which means <code>$username</code> can impersonate members of any
group. Defaults to an empty list that is equivalent to <code>$username</code>
is not allowed to impersonate members from any group.</li>
+ <li><code>hadoop.proxyuser.$username.hosts</code> - indicates a list of
hostnames from where the requests are allowed to be accepted in case the
<code>doAs</code> parameter is used when impersonating requests. It is possible
to set this to a 1-element list using the <code>*</code> wildcard which means
<code>$username</code> can impersonate incoming requests from any host.
Defaults to an empty list that is equivalent to <code>$username</code> is not
allowed to impersonate requests from any host.</li>
+</ul>
+<p>Please note this configuration is applied <strong>iff</strong> the
<code>doAs</code> query parameter is present in the incoming request and
impersonation is enabled in the affected topology.</p>
+<p><em><strong>Important note:</strong></em> this new-type impersonation
support on the identity assertion layer is ignored if the topology uses the
<code>HadoopAuth</code> authentication provider because the <code>doAs</code>
support is working OOTB there, therefore a second authorization is useless
going forward.</p>
+<p>It’s also worth articulating that Hadoop Proxyuser-based
impersonation works together with the already existing principal mapping (see
below). At first, Knox applies the Hadoop Proxyuser impersonation, then it
proceeds with principal mappings (if any). Let see a sample:</p>
+<ul>
+ <li><code>hadoop.proxyuser.admin.users</code> is set to <code>bob</code>
(<code>admin</code> is allowed to impersonate <code>bob</code>)</li>
+ <li><code>principal.mapping</code> is set to <code>bob=tom</code>
(<code>bob</code> is mapped as <code>tom</code> )</li>
+</ul>
+<p>The <code>admin</code> user sends the following request:</p>
+<pre><code>curl https://KNOX_HOST:8443/gateway/sandbox/service/path?doAs=bob
+</code></pre>
+<p>In the request processing flow, after the identity assertion phase is
completed, <code>tom</code> will be the effective user. As you can see, the
rules were applied transitively.</p>
+<p>For other use cases you may want to check out <a
href="https://github.com/apache/knox/pull/681";>GitHub Pull Request #681</a>.</p>
<h6><a id="Principal+Mapping">Principal Mapping</a> <a
href="#Principal+Mapping"><img src="markbook-section-link.png"/></a></h6>
<pre><code><param>
<name>principal.mapping</name>
@@ -5969,11 +6006,6 @@ APACHE_HOME/bin/apachectl -k stop
<td> </td>
</tr>
<tr>
- <td>knox.token.impersonation.enabled </td>
- <td>This is a <code>boolean</code> flag indicates if token impersonation
is enabled </td>
- <td><code>true</code> </td>
- </tr>
- <tr>
<td>knox.token.issuer </td>
<td>This is an optional configuration parameter to specify the issuer of
a token. </td>
<td>KNOXSSO </td>
@@ -6143,7 +6175,7 @@ APACHE_HOME/bin/apachectl -k stop
<li>comment: this is an <em>optional</em> input field that allows end-users
to add meaningful comments (mnemonics) to their generated tokens. The maximum
length is 255 characters.</li>
<li>the <code>Configured maximum lifetime</code> informs the clients about
the <code>knox.token.ttl</code> property set in the <code>homepage</code>
topology (defaults to 120 days). If that property is not set (e.g. someone
removes it from he homepage topology), Knox uses a hard-coded value of 30
seconds (aka. default Knox token TTL)</li>
<li>Custom token lifetime can be set by adjusting the days/hours/minutes
spinners. The default configuration will yield one hour.</li>
- <li>Token impersonation: an optional free text input field tha makes it
possible to generate a token for someone else.</li>
+ <li>Token impersonation: an optional free text input field that makes it
possible to generate a token for someone else.</li>
<li>Clicking the Generate Token button will try to create a token for
you.</li>
</ul>
<h5><a id="About+the+generated+token+TTL">About the generated token TTL</a> <a
href="#About+the+generated+token+TTL"><img
src="markbook-section-link.png"/></a></h5>
@@ -6197,16 +6229,9 @@ APACHE_HOME/bin/apachectl -k stop
</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>
<h5><a id="Token+impersonation">Token impersonation</a> <a
href="#Token+impersonation"><img src="markbook-section-link.png"/></a></h5>
-<p>From v2.0.0, an authenticated user can generate token(s) on behalf of other
user(s). This feature was implemented in <a
href="https://issues.apache.org/jira/browse/KNOX-2714";>KNOX-2714</a> and
requires the following configuration to work:</p>
-<ul>
- <li><code>knox.token.impersonation.enabled</code> - a <code>boolean</code>
flag indicates if token impersonation is enabled. Defaults to
<code>true</code></li>
- <li><code>knox.token.proxyuser.$username.users</code> - indicates the list
of users for whom <code>$username</code> is allowed to create tokens. It is
possible to set this to a 1-element list using the <code>*</code> wildcard
which means <code>$username</code> can generate tokens for everyone. Defaults
to an empty list that is equivalent to <code>$username</code> is not allowed to
impersonate anyone.</li>
- <li><code>knox.token.proxyuser.$username.groups</code> - indicates the list
of group names for whose members <code>$username</code> is allowed to create
tokens for. It is possible to set this to a 1-element list using the
<code>*</code> wildcard which means <code>$username</code> can generate tokens
for members of any group. Defaults to an empty list that is equivalent to
<code>$username</code> is not allowed to impersonate members from any
group.</li>
- <li><code>knox.token.proxyuser.$username.hosts</code> - indicates a list of
hostnames from where the requests are allowed to be accepted in case the
<code>doAs</code> parameter is used when creating Knox Tokens. It is possible
to set this to a 1-element list using the <code>*</code> wildcard which means
<code>$username</code> can generate tokens from any host. Defaults to an empty
list that is equivalent to <code>$username</code> is not allowed to create
tokens from any host.</li>
-</ul>
-<p>Please note this configuration is applied <strong>iff</strong> the newly
introduced <code>doAs</code> query parameter is present in the token generation
request AND if server-managed token state is enabled in the affected topology.
You may want to check out <a
href="https://github.com/apache/knox/pull/545";>GitHub Pull Request #545</a> for
sample configuration.</p>
<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>
+<p>For this to work, the topology has to be configured with the HadoopAuth
authentication provider, or an identity assertion provider where impersonation
is enabled In both cases, <code>doAs</code> support will only work with a valid
Hadoop proxyuser configuration (see <a
href="#Hadoop+Proxyuser+impersonation">Hadoop Proxyuser impersonation</a>
above)</p>
<h5><a id="Token+metadata">Token metadata</a> <a href="#Token+metadata"><img
src="markbook-section-link.png"/></a></h5>
<p>As indicated above, the <code>KNOXTOKEN</code> service maintains some
hard-coded token metadata out-of-the-box:</p>
<ul>
Modified: knox/site/index.html
URL:
http://svn.apache.org/viewvc/knox/site/index.html?rev=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Fri Dec 23 10:54:33 2022
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2022-12-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2022-12-23
| 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="20221213" />
+ <meta name="Date-Revision-yyyymmdd" content="20221223" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Announcing Apache Knox 1.6.1!</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: 2022-12-13</li>
+ <li id="publishDate">Last Published: 2022-12-23</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=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/site/issue-management.html (original)
+++ knox/site/issue-management.html Fri Dec 23 10:54:33 2022
@@ -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 2022-12-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 2022-12-23
| 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="20221213" />
+ <meta name="Date-Revision-yyyymmdd" content="20221223" />
<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: 2022-12-13</li>
+ <li id="publishDate">Last Published: 2022-12-23</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/licenses.html
URL:
http://svn.apache.org/viewvc/knox/site/licenses.html?rev=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/site/licenses.html (original)
+++ knox/site/licenses.html Fri Dec 23 10:54:33 2022
@@ -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
2022-12-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
2022-12-23
| 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="20221213" />
+ <meta name="Date-Revision-yyyymmdd" content="20221223" />
<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: 2022-12-13</li>
+ <li id="publishDate">Last Published: 2022-12-23</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=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/site/mailing-lists.html (original)
+++ knox/site/mailing-lists.html Fri Dec 23 10:54:33 2022
@@ -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 2022-12-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 2022-12-23
| 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="20221213" />
+ <meta name="Date-Revision-yyyymmdd" content="20221223" />
<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: 2022-12-13</li>
+ <li id="publishDate">Last Published: 2022-12-23</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=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Fri Dec 23 10:54:33 2022
@@ -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 2022-12-13
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-site-plugin:3.7.1:CategorySummaryDocumentRenderer
at 2022-12-23
| 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="20221213" />
+ <meta name="Date-Revision-yyyymmdd" content="20221223" />
<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: 2022-12-13</li>
+ <li id="publishDate">Last Published: 2022-12-23</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/team.html
URL:
http://svn.apache.org/viewvc/knox/site/team.html?rev=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/site/team.html (original)
+++ knox/site/team.html Fri Dec 23 10:54:33 2022
@@ -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
2022-12-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
2022-12-23
| 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="20221213" />
+ <meta name="Date-Revision-yyyymmdd" content="20221223" />
<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: 2022-12-13</li>
+ <li id="publishDate">Last Published: 2022-12-23</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/trunk/books/2.0.0/config_id_assertion.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.0.0/config_id_assertion.md?rev=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/trunk/books/2.0.0/config_id_assertion.md (original)
+++ knox/trunk/books/2.0.0/config_id_assertion.md Fri Dec 23 10:54:33 2022
@@ -47,6 +47,22 @@ This particular configuration indicates
<name>group.principal.mapping</name>
<value>*=users;hdfs=admin</value>
</param>
+ <param>
+ <name>hadoop.proxyuser.impersonation.enabled</name>
+ <value>false</value>
+ </param>
+ <param>
+ <name>hadoop.proxyuser.admin.users</name>
+ <value>*</value>
+ </param>
+ <param>
+ <name>hadoop.proxyuser.admin.groups</name>
+ <value>*</value>
+ </param>
+ <param>
+ <name>hadoop.proxyuser.admin.hosts</name>
+ <value>*</value>
+ </param>
</provider>
This configuration identifies the same identity assertion provider but does
provide principal and group mapping rules. In this case, when a user is
authenticated as "guest" his identity is actually asserted to the Hadoop
cluster as "hdfs". In addition, since there are group principal mappings
defined, he will also be considered as a member of the groups "users" and
"admin". In this particular example the wildcard "*" is used to indicate that
all authenticated users need to be considered members of the "users" group and
that only the user "hdfs" is mapped to be a member of the "admin" group.
@@ -61,6 +77,34 @@ When a principal mapping is defined that
If there is no mapping to another principal then the authenticated or primary
principal is the effective principal.
+Another way to impersonate principals is to apply Hadoop Proxyuser-based
impersonations as described in the next section.
+
+##### Hadoop Proxyuser impersonation
+
+From v2.0.0, an authenticated user can impersonate other user(s) leveraging
Hadoop's proxuyser configuration mechanism. This feature was implemented in
[KNOX-2839](https://issues.apache.org/jira/browse/KNOX-2839) and requires the
following configuration to work:
+
+* `hadoop.proxyuser.impersonation.enabled` - a `boolean` flag indicates if
token impersonation is enabled. Defaults to `true`
+* `hadoop.proxyuser.$username.users` - indicates the list of users for whom
`$username` is allowed to impersonate. It is possible to set this to a
1-element list using the `*` wildcard which means `$username` can impersonate
everyone. Defaults to an empty list that is equivalent to `$username` is not
allowed to impersonate anyone.
+* `hadoop.proxyuser.$username.groups` - indicates the list of group names for
whose members `$username` is allowed to impersonate. It is possible to set this
to a 1-element list using the `*` wildcard which means `$username` can
impersonate members of any group. Defaults to an empty list that is equivalent
to `$username` is not allowed to impersonate members from any group.
+* `hadoop.proxyuser.$username.hosts` - indicates a list of hostnames from
where the requests are allowed to be accepted in case the `doAs` parameter is
used when impersonating requests. It is possible to set this to a 1-element
list using the `*` wildcard which means `$username` can impersonate incoming
requests from any host. Defaults to an empty list that is equivalent to
`$username` is not allowed to impersonate requests from any host.
+
+Please note this configuration is applied **iff** the `doAs` query parameter
is present in the incoming request and impersonation is enabled in the affected
topology.
+
+_**Important note:**_ this new-type impersonation support on the identity
assertion layer is ignored if the topology uses the `HadoopAuth` authentication
provider because the `doAs` support is working OOTB there, therefore a second
authorization is useless going forward.
+
+It's also worth articulating that Hadoop Proxyuser-based impersonation works
together with the already existing principal mapping (see below). At first,
Knox applies the Hadoop Proxyuser impersonation, then it proceeds with
principal mappings (if any). Let see a sample:
+
+ * `hadoop.proxyuser.admin.users` is set to `bob` (`admin` is allowed to
impersonate `bob`)
+ * `principal.mapping` is set to `bob=tom` (`bob` is mapped as `tom` )
+
+The `admin` user sends the following request:
+
+ curl https://KNOX_HOST:8443/gateway/sandbox/service/path?doAs=bob
+
+In the request processing flow, after the identity assertion phase is
completed, `tom` will be the effective user. As you can see, the rules were
applied transitively.
+
+For other use cases you may want to check out [GitHub Pull Request
#681](https://github.com/apache/knox/pull/681).
+
###### Principal Mapping ######
<param>
Modified: knox/trunk/books/2.0.0/config_knox_token.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.0.0/config_knox_token.md?rev=1906185&r1=1906184&r2=1906185&view=diff
==============================================================================
--- knox/trunk/books/2.0.0/config_knox_token.md (original)
+++ knox/trunk/books/2.0.0/config_knox_token.md Fri Dec 23 10:54:33 2022
@@ -38,7 +38,6 @@ knox.token.renewer.whitelist | This is
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) |
knox.token.type | If this is configured the generated JWT's header will have
this value as the `typ` property | |
-knox.token.impersonation.enabled | This is a `boolean` flag indicates if token
impersonation is enabled | `true` |
knox.token.issuer | This is an optional configuration parameter to specify
the issuer of a token. | KNOXSSO |
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.
@@ -248,7 +247,7 @@ The following sections are displayed on
* comment: this is an _optional_ input field that allows end-users to add
meaningful comments (mnemonics) to their generated tokens. The maximum length
is 255 characters.
* the `Configured maximum lifetime` informs the clients about the
`knox.token.ttl` property set in the `homepage` topology (defaults to 120
days). If that property is not set (e.g. someone removes it from he homepage
topology), Knox uses a hard-coded value of 30 seconds (aka. default Knox token
TTL)
* Custom token lifetime can be set by adjusting the days/hours/minutes
spinners. The default configuration will yield one hour.
-* Token impersonation: an optional free text input field tha makes it
possible to generate a token for someone else.
+* Token impersonation: an optional free text input field that makes it
possible to generate a token for someone else.
* Clicking the Generate Token button will try to create a token for you.
##### About the generated token TTL
@@ -317,19 +316,14 @@ In order to refresh the table, you can u
##### Token impersonation
-From v2.0.0, an authenticated user can generate token(s) on behalf of other
user(s). This feature was implemented in
[KNOX-2714](https://issues.apache.org/jira/browse/KNOX-2714) and requires the
following configuration to work:
-
-* `knox.token.impersonation.enabled` - a `boolean` flag indicates if token
impersonation is enabled. Defaults to `true`
-* `knox.token.proxyuser.$username.users` - indicates the list of users for
whom `$username` is allowed to create tokens. It is possible to set this to a
1-element list using the `*` wildcard which means `$username` can generate
tokens for everyone. Defaults to an empty list that is equivalent to
`$username` is not allowed to impersonate anyone.
-* `knox.token.proxyuser.$username.groups` - indicates the list of group names
for whose members `$username` is allowed to create tokens for. It is possible
to set this to a 1-element list using the `*` wildcard which means `$username`
can generate tokens for members of any group. Defaults to an empty list that is
equivalent to `$username` is not allowed to impersonate members from any group.
-* `knox.token.proxyuser.$username.hosts` - indicates a list of hostnames from
where the requests are allowed to be accepted in case the `doAs` parameter is
used when creating Knox Tokens. It is possible to set this to a 1-element list
using the `*` wildcard which means `$username` can generate tokens from any
host. Defaults to an empty list that is equivalent to `$username` is not
allowed to create tokens from any host.
-
-Please note this configuration is applied **iff** the newly introduced `doAs`
query parameter is present in the token generation request AND if
server-managed token state is enabled in the affected topology.
-You may want to check out [GitHub Pull Request
#545](https://github.com/apache/knox/pull/545) for sample configuration.
-
On the token generation page end-users can generate tokens on behalf of other
users by specifying the desired user name in the token `impersonation` field.
The following screenshot sows a successful token generation for user `tom` (the
logged in user is `admin`).
+
+For this to work, the topology has to be configured with
+the HadoopAuth authentication provider, or
+an identity assertion provider where impersonation is enabled
+In both cases, `doAs` support will only work with a valid Hadoop proxyuser
configuration (see [Hadoop Proxyuser
impersonation](#Hadoop+Proxyuser+impersonation) above)
##### Token metadata
