You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by "ASF GitHub Bot (JIRA)" <ji...@apache.org> on 2018/02/05 19:09:00 UTC
[jira] [Commented] (KAFKA-6452) Add documentation for delegation
token authentication mechanism
[ https://issues.apache.org/jira/browse/KAFKA-6452?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16352789#comment-16352789 ]
ASF GitHub Bot commented on KAFKA-6452:
---------------------------------------
junrao closed pull request #4490: KAFKA-6452: Add documentation for delegation token authentication
URL: https://github.com/apache/kafka/pull/4490
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/security.html b/docs/security.html
index 4e401aec186..3e3c818571a 100644
--- a/docs/security.html
+++ b/docs/security.html
@@ -661,6 +661,108 @@ <h3><a id="security_sasl" href="#security_sasl">7.3 Authentication using SASL</a
old mechanism from JAAS config file. Incrementally bounce the cluster again.</li>
</ol>
</li>
+
+ <li><h4><a id="security_delegation_token" href="#security_delegation_token">Authentication using Delegation Tokens</a></h4>
+ <p>Delegation token based authentication is a lightweight authentication mechanism to complement existing SASL/SSL
+ methods. Delegation tokens are shared secrets between kafka brokers and clients. Delegation tokens will help processing
+ frameworks to distribute the workload to available workers in a secure environment without the added cost of distributing
+ Kerberos TGT/keytabs or keystores when 2-way SSL is used. See <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-48+Delegation+token+support+for+Kafka">KIP-48</a>
+ for more details.</p>
+
+ <p>Typical steps for delegation token usage are:</p>
+ <ol>
+ <li>User authenticates with the Kafka cluster via SASL or SSL, and obtains a delegation token. This can be done
+ using AdminClient APIs or using <tt>kafka-delegation-token.sh</tt> script.</li>
+ <li>User securely passes the delegation token to Kafka clients for authenticating with the Kafka cluster.</li>
+ <li>Token owner/renewer can renew/expire the delegation tokens.</li>
+ </ol>
+
+ <ol>
+ <li><h5><a id="security_token_management" href="#security_token_management">Token Management</a></h5>
+ <p> A master key/secret is used to generate and verify delegation tokens. This is supplied using config
+ option <tt>delegation.token.master.key</tt>. Same secret key must be configured across all the brokers.
+ If the secret is not set or set to empty string, brokers will disable the delegation token authentication.</p>
+
+ <p>In current implementation, token details are stored in Zookeeper and is suitable for use in Kafka installations where
+ Zookeeper is on a private network. Also currently, master key/secret is stored as plain text in server.properties
+ config file. We intend to make these configurable in a future Kafka release.</p>
+
+ <p>A token has a current life, and a maximum renewable life. By default, tokens must be renewed once every 24 hours
+ for up to 7 days. These can be configured using <tt>delegation.token.expiry.time.ms</tt>
+ and <tt>delegation.token.max.lifetime.ms</tt> config options.</p>
+
+ <p>Tokens can also be cancelled explicitly. If a token is not renewed by the token’s expiration time or if token
+ is beyond the max life time, it will be deleted from all broker caches as well as from zookeeper.</p>
+ </li>
+
+ <li><h5><a id="security_sasl_create_tokens" href="#security_sasl_create_tokens">Creating Delegation Tokens</a></h5>
+ <p>Tokens can be created by using AdminClient APIs or using <tt>kafka-delegation-token.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.
+ <tt>kafka-delegation-token.sh</tt> script examples are given below.</p>
+ <p>Create a delegation token:
+ <pre class="brush: bash;">
+ > bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --create --max-life-time-period -1 --command-config client.properties --renewer-principal User:user1
+ </pre>
+ <p>Renew a delegation token:
+ <pre class="brush: bash;">
+ > bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --renew --renew-time-period -1 --command-config client.properties --hmac ABCDEFGHIJK
+ </pre>
+ <p>Expire a delegation token:
+ <pre class="brush: bash;">
+ > bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --expire --expiry-time-period -1 --command-config client.properties --hmac ABCDEFGHIJK
+ </pre>
+ <p>Existing tokens can be described using the --describe option:
+ <pre class="brush: bash;">
+ > bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --describe --command-config client.properties --owner-principal User:user1
+ </pre>
+ </li>
+ <li><h5><a id="security_token_authentication" href="#security_token_authentication">Token Authentication</a></h5>
+ <p>Delegation token authentication piggybacks on the current SASL/SCRAM authentication mechanism. We must enable
+ SASL/SCRAM mechanism on Kafka cluster as described in <a href="#security_sasl_scram">here</a>.</p>
+
+ <p>Configuring Kafka Clients:</p>
+ <ol>
+ <li>Configure the JAAS configuration property for each client in producer.properties or consumer.properties.
+ The login module describes how the clients like producer and consumer can connect to the Kafka Broker.
+ The following is an example configuration for a client for the token authentication:
+ <pre class="brush: text;">
+ sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \
+ username="tokenID123" \
+ password="lAYYSFmLs4bTjf+lTZ1LCHR/ZZFNA==" \
+ tokenauth="true";</pre>
+
+ <p>The options <tt>username</tt> and <tt>password</tt> are used by clients to configure the token id and
+ token HMAC. And the option <tt>tokenauth</tt> is used to indicate the server about token authentication.
+ In this example, clients connect to the broker using token id: <i>tokenID123</i>. Different clients within a
+ JVM may connect using different tokens by specifying different token details in <code>sasl.jaas.config</code>.</p>
+
+ <p>JAAS configuration for clients may alternatively be specified as a JVM parameter similar to brokers
+ as described <a href="#security_client_staticjaas">here</a>. Clients use the login section named
+ <tt>KafkaClient</tt>. This option allows only one user for all client connections from a JVM.</p></li>
+ </ol>
+ </li>
+
+ <li><h5><a id="security_token_secret_rotation" href="#security_token_secret_rotation">Procedure to manually rotate the secret:</a></h5>
+ <p>We require a re-deployment when the secret needs to be rotated. During this process, already connected clients
+ will continue to work. But any new connection requests and renew/expire requests with old tokens can fail. Steps are given below.</p>
+
+ <ol>
+ <li>Expire all existing tokens.</li>
+ <li>Rotate the secret by rolling upgrade, and</li>
+ <li>Generate new tokens</li>
+ </ol>
+ <p>We intend to automate this in a future Kafka release.</p>
+ </li>
+
+ <li><h5><a id="security_token_notes" 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>
<h3><a id="security_authz" href="#security_authz">7.4 Authorization and ACLs</a></h3>
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
> Add documentation for delegation token authentication mechanism
> ---------------------------------------------------------------
>
> Key: KAFKA-6452
> URL: https://issues.apache.org/jira/browse/KAFKA-6452
> Project: Kafka
> Issue Type: Sub-task
> Components: documentation
> Reporter: Manikumar
> Assignee: Manikumar
> Priority: Major
> Fix For: 1.1.0
>
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)