This is an automated email from the ASF dual-hosted git repository.
manikumar pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 277c4c2e97 KAFKA-6945: Add docs about KIP-373 (#12346)
277c4c2e97 is described below
commit 277c4c2e97d2aef096ab0e998fdd1ae513508798
Author: Viktor Somogyi-Vass <[email protected]>
AuthorDate: Tue Jul 5 13:59:31 2022 +0200
KAFKA-6945: Add docs about KIP-373 (#12346)
Reviewers: Manikumar Reddy
---
docs/security.html | 42 +++++++++++++++++++++++++++++++++---------
1 file changed, 33 insertions(+), 9 deletions(-)
diff --git a/docs/security.html b/docs/security.html
index 21ec72cec5..d9b26f5d15 100644
--- a/docs/security.html
+++ b/docs/security.html
@@ -1080,9 +1080,14 @@ sasl.mechanism.inter.broker.protocol=GSSAPI (or one of
the other enabled mechani
<p>Tokens can be created by using Admin APIs or using
<tt>kafka-delegation-tokens.sh</tt> script.
Delegation token requests
(create/renew/expire/describe) should be issued only on SASL or SSL
authenticated channels.
Tokens can not be requests if the initial
authentication is done through delegation token.
+ A token can be created by the user for that user or
others as well by specifying the <tt>--owner-principal</tt> parameter.
+ Owner/Renewers can renew or expire tokens.
Owner/renewers can always describe their own tokens.
+ To describe other tokens, a DESCRIBE_TOKEN permission
needs to be added on the User resource representing the owner of the token.
<tt>kafka-delegation-tokens.sh</tt> script examples
are given below.</p>
<p>Create a delegation token:
<pre class="line-numbers"><code class="language-bash">>
bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --create
--max-life-time-period -1 --command-config client.properties
--renewer-principal User:user1</code></pre>
+ <p>Create a delegation token for a different owner:
+ <pre class="line-numbers"><code class="language-bash">>
bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --create
--max-life-time-period -1 --command-config client.properties
--renewer-principal User:user1 --owner-principal User:owner1</code></pre>
<p>Renew a delegation token:
<pre class="line-numbers"><code class="language-bash">>
bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --renew
--renew-time-period -1 --command-config client.properties --hmac
ABCDEFGHIJK</code></pre>
<p>Expire a delegation token:
@@ -1126,13 +1131,6 @@ sasl.mechanism.inter.broker.protocol=GSSAPI (or one of
the other enabled mechani
</ol>
<p>We intend to automate this in a future Kafka
release.</p>
</li>
-
- <li><h5 class="anchor-heading"><a id="security_token_notes"
class="anchor-link"></a><a href="#security_token_notes">Notes on Delegation
Tokens</a></h5>
- <ul>
- <li>Currently, we only allow a user to create
delegation token for that user only. Owner/Renewers can renew or expire tokens.
- Owner/renewers can always describe their own
tokens. To describe others tokens, we need to add DESCRIBE permission on Token
Resource.</li>
- </ul>
- </li>
</ol>
</li>
</ol>
@@ -1266,6 +1264,13 @@
RULE:[n:string](regexp)s/pattern/replacement/g/U</code></pre>
<td></td>
<td>ResourcePattern</td>
</tr>
+ <tr>
+ <td>--user-principal [user-principal]</td>
+ <td>A user resource to which ACLs should be added or removed. This
is currently supported in relation with delegation tokens.
+ A value of * indicates ACL should apply to all users.</td>
+ <td></td>
+ <td>ResourcePattern</td>
+ </tr>
<tr>
<td>--resource-pattern-type [pattern-type]</td>
<td>Indicates to the script the type of resource pattern, (for
--add), or resource pattern filter, (for --list and --remove), the user wishes
to use.<br>
@@ -1323,6 +1328,8 @@
RULE:[n:string](regexp)s/pattern/replacement/g/U</code></pre>
<li>DescribeConfigs</li>
<li>AlterConfigs</li>
<li>IdempotentWrite</li>
+ <li>CreateTokens</li>
+ <li>DescribeTokens</li>
<li>All</li>
</ul>
</td>
@@ -1418,9 +1425,10 @@
RULE:[n:string](regexp)s/pattern/replacement/g/U</code></pre>
Users having Alter permission on ClusterResource can use Admin API
for ACL management. kafka-acls.sh script supports AdminClient API to manage
ACLs without interacting with zookeeper/authorizer directly.
All the above examples can be executed by using
<b>--bootstrap-server</b> option. For example:
- <pre class="line-numbers"><code class="language-bash">>
bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config
/tmp/adminclient-configs.conf --add --allow-principal User:Bob --producer
--topic Test-topic
+ <pre class="line-numbers"><code
class="language-bash">bin/kafka-acls.sh --bootstrap-server localhost:9092
--command-config /tmp/adminclient-configs.conf --add --allow-principal User:Bob
--producer --topic Test-topic
bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config
/tmp/adminclient-configs.conf --add --allow-principal User:Bob --consumer
--topic Test-topic --group Group-1
-bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config
/tmp/adminclient-configs.conf --list --topic Test-topic</code></pre></li>
+bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config
/tmp/adminclient-configs.conf --list --topic Test-topic
+bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config
/tmp/adminclient-configs.conf --add --allow-principal User:tokenRequester
--operation CreateTokens --user-principal "owner1"</code></pre></li>
</ul>
@@ -1442,6 +1450,8 @@ bin/kafka-acls.sh --bootstrap-server localhost:9092
--command-config /tmp/adminc
<li>DescribeConfigs</li>
<li>AlterConfigs</li>
<li>IdempotentWrite</li>
+ <li>CreateTokens</li>
+ <li>DescribeTokens</li>
<li>All</li>
</ul>
<h5 class="anchor-heading"><a id="resources_in_kafka"
class="anchor-link"></a><a href="#resources_in_kafka">Resources in
Kafka</a></h5>
@@ -1463,6 +1473,8 @@ bin/kafka-acls.sh --bootstrap-server localhost:9092
--command-config /tmp/adminc
a little special behavior in Kafka it is recommended to read
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-48+Delegation+token+support+for+Kafka#KIP-48DelegationtokensupportforKafka-DescribeDelegationTokenRequest";>KIP-48</a>
and the related upstream documentation at <a
href="#security_delegation_token">Authentication using Delegation
Tokens</a>.</li>
+ <li><b>User:</b> CreateToken and DescribeToken operations can be
granted to User resources to allow creating and describing
+ tokens for other users. More info can be found in <a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-373%3A+Allow+users+to+create+delegation+tokens+for+other+users";>KIP-373</a>.</li>
</ul>
<h5 class="anchor-heading"><a id="operations_resources_and_protocols"
class="anchor-link"></a><a
href="#operations_resources_and_protocols">Operations and Resources on
Protocols</a></h5>
<p>In the below table we'll list the valid operations on resources that
are executed by the Kafka API protocols.</p>
@@ -1838,6 +1850,12 @@ bin/kafka-acls.sh --bootstrap-server localhost:9092
--command-config /tmp/adminc
<td>Creating delegation tokens has special rules, for this please
see the
<a id="security_delegation_token_1"
href="#security_delegation_token">Authentication using Delegation Tokens</a>
section.</td>
</tr>
+ <tr>
+ <td>CREATE_DELEGATION_TOKEN (38)</td>
+ <td>CreateTokens</td>
+ <td>User</td>
+ <td>Allows creating delegation tokens for the User resource.</td>
+ </tr>
<tr>
<td>RENEW_DELEGATION_TOKEN (39)</td>
<td></td>
@@ -1859,6 +1877,12 @@ bin/kafka-acls.sh --bootstrap-server localhost:9092
--command-config /tmp/adminc
<td>Describing delegation tokens has special rules, for this
please see the
<a id="security_delegation_token_4"
href="#security_delegation_token">Authentication using Delegation Tokens</a>
section.</td>
</tr>
+ <tr>
+ <td>DESCRIBE_DELEGATION_TOKEN (41)</td>
+ <td>DescribeTokens</td>
+ <td>User</td>
+ <td>Allows describing delegation tokens of the User resource.</td>
+ </tr>
<tr>
<td>DELETE_GROUPS (42)</td>
<td>Delete</td>
