diff --git a/docs/security.html b/docs/security.html index 8cb867eb04c..81d5c403c13 100644 --- a/docs/security.html +++ b/docs/security.html @@ -19,8 +19,12 @@

7.1 Security Overview

In release 0.9.0.0, the Kafka community added a number of features that, used either separately or together, increases security in a Kafka cluster. The following security measures are currently supported:
    -
  1. Authentication of connections to brokers from clients (producers and consumers), other brokers and tools, using either SSL or SASL (Kerberos). - SASL/PLAIN can also be used from release 0.10.0.0 onwards.
    2. +
  2. Authentication of connections to brokers from clients (producers and consumers), other brokers and tools, using either SSL or SASL. Kafka supports the following SASL mechanisms: +
  3. Authentication of connections from brokers to ZooKeeper
  4. Encryption of data transferred between brokers and clients, between brokers, or between brokers and tools using SSL (Note that there is a performance degradation when SSL is enabled, the magnitude of which depends on the CPU type and the JVM implementation.)
  5. Authorization of read / write operations by clients
    6. @@ -211,117 +215,125 @@

    7.3 Authentication using SASL

      -

    1. SASL configuration for Kafka brokers

      +

    2. JAAS configuration

      +

      Kafka uses the Java Authentication and Authorization Service + (JAAS) + for SASL configuration.

        -
      1. Select one or more supported mechanisms to enable in the broker. GSSAPI - and PLAIN are the mechanisms currently supported in Kafka.
        2. -
      2. Add a JAAS config file for the selected mechanisms as described in the examples - for setting up GSSAPI (Kerberos) - or PLAIN.
        3. -
      3. Pass the JAAS config file location as JVM parameter to each Kafka broker. - For example: - 
            -Djava.security.auth.login.config=/etc/kafka/kafka_server_jaas.conf
        4. -
      4. Configure a SASL port in server.properties, by adding at least one of - SASL_PLAINTEXT or SASL_SSL to the listeners parameter, which - contains one or more comma-separated values: - 
            listeners=SASL_PLAINTEXT://host.name:port
        - If SASL_SSL is used, then SSL must also be - configured. If you are only configuring a SASL port (or if you want - the Kafka brokers to authenticate each other using SASL) then make sure - you set the same SASL protocol for inter-broker communication: - 
            security.inter.broker.protocol=SASL_PLAINTEXT (or SASL_SSL)
        5. -
      5. Enable one or more SASL mechanisms in server.properties: - 
            sasl.enabled.mechanisms=GSSAPI (,PLAIN)
        6. -
      6. Configure the SASL mechanism for inter-broker communication in server.properties - if using SASL for inter-broker communication: - 
            sasl.mechanism.inter.broker.protocol=GSSAPI (or PLAIN)
        7. -
      7. Follow the steps in GSSAPI (Kerberos) - or PLAIN to configure SASL - for the enabled mechanisms. To enable multiple mechanisms in the broker, follow - the steps here.
        8. - Important notes: -
          -
        1. KafkaServer is the section name in the JAAS file used by each +
        2. JAAS configuration for Kafka brokers
          + +

          KafkaServer is the section name in the JAAS file used by each KafkaServer/Broker. This section provides SASL configuration options for the broker including any SASL client connections made by the broker - for inter-broker communication.

          3. -
        3. Client section is used to authenticate a SASL connection with + for inter-broker communication.

          + +

          Client section is used to authenticate a SASL connection with zookeeper. It also allows the brokers to set SASL ACL on zookeeper nodes which locks these nodes down so that only the brokers can modify it. It is necessary to have the same principal name across all brokers. If you want to use a section name other than Client, set the system property zookeeper.sasl.client to the appropriate - name (e.g., -Dzookeeper.sasl.client=ZkClient).

          4. -
        4. ZooKeeper uses "zookeeper" as the service name by default. If you + name (e.g., -Dzookeeper.sasl.client=ZkClient).

          + +

          ZooKeeper uses "zookeeper" as the service name by default. If you want to change this, set the system property zookeeper.sasl.client.username to the appropriate name - (e.g., -Dzookeeper.sasl.client.username=zk).

          5. -
        -
      -
      3. -

    3. SASL configuration for Kafka clients

      - SASL authentication is only supported for the new Java Kafka producer and - consumer, the older API is not supported. JAAS configuration for clients may - be specified as a static JAAS config file or using the client configuration property - sasl.jaas.config. - To configure SASL authentication on the clients: -
        -
      1. Select a SASL mechanism for authentication.
        2. -
      2. Configure the following properties in producer.properties or - consumer.properties: - 
            security.protocol=SASL_PLAINTEXT (or SASL_SSL)
-    sasl.mechanism=GSSAPI (or PLAIN)
        3. -
      3. Follow the steps in GSSAPI (Kerberos) - or PLAIN to configure SASL - for the selected mechanism.
        4. -
      4. Configure JAAS using client configuration property - or static JAAS config file as described below.
        5. -
      -
        -
      1. JAAS configuration using client configuration property
        -

        Clients may specify JAAS configuration as a producer or consumer property without - creating a physical configuration file. This mode also enables different producers - and consumers within the same JVM to use different credentials by specifying - different properties for each client. If both static JAAS configuration system property - java.security.auth.login.config and client property sasl.jaas.config - are specified, the client property will be used.

        + (e.g., -Dzookeeper.sasl.client.username=zk).

        2. + +
      2. JAAS configuration for Kafka clients
        + +

        Clients may configure JAAS using the client configuration property + sasl.jaas.config + or using the static JAAS config file + similar to brokers.

        - To configure SASL authentication on the clients using configuration property:
          -
        1. Configure the property sasl.jaas.config in producer.properties or - consumer.properties to be the JAAS login module section of the selected mechanism. - For example, PLAIN - credentials may be configured as: - 
              sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="alice" password="alice-secret";
          2. - See GSSAPI (Kerberos) or PLAIN - for full example configurations. -
        -
        3. -
      3. JAAS configuration using static config file
        - To configure SASL authentication on the clients using static JAAS config file: -
          -
        1. Add a JAAS config file with a client login section named KafkaClient. Configure - a login module in KafkaClient for the selected mechanism as described in the examples - for setting up GSSAPI (Kerberos) - or PLAIN. - For example, GSSAPI - credentials may be configured as: - 
          -    KafkaClient {
+            
        2. JAAS configuration using client configuration property
          
+                
          Clients may specify JAAS configuration as a producer or consumer property without
+                creating a physical configuration file. This mode also enables different producers
+                and consumers within the same JVM to use different credentials by specifying
+                different properties for each client. If both static JAAS configuration system property
+                java.security.auth.login.config and client property sasl.jaas.config
+                are specified, the client property will be used.
          
+
+                
          See GSSAPI (Kerberos),
+                PLAIN or
+                SCRAM for example configurations.
          3. 
+
+                
        3. JAAS configuration using static config file
          
+                To configure SASL authentication on the clients using static JAAS config file:
+                
            
+                
          1. Add a JAAS config file with a client login section named KafkaClient. Configure
+                    a login module in KafkaClient for the selected mechanism as described in the examples
+                    for setting up GSSAPI (Kerberos),
+                    PLAIN or
+                    SCRAM.
+                    For example, GSSAPI
+                    credentials may be configured as:
+                    
            +        KafkaClient {
         com.sun.security.auth.module.Krb5LoginModule required
         useKeyTab=true
         storeKey=true
         keyTab="/etc/security/keytabs/kafka_client.keytab"
         principal="kafka-client-1@EXAMPLE.COM";
     };
            
-                See GSSAPI (Kerberos) or PLAIN
-                for example configurations of each mechanism.
            2. 
-            
          2. Pass the JAAS config file location as JVM parameter to each client JVM. For example:
-                
                -Djava.security.auth.login.config=/etc/kafka/kafka_client_jaas.conf
            3. 
+                
+                
          3. Pass the JAAS config file location as JVM parameter to each client JVM. For example:
+                    
                -Djava.security.auth.login.config=/etc/kafka/kafka_client_jaas.conf
            4. 
+	
          
+                
          4. 
+
        +
        4. +
      +
      4. +

    4. SASL configuration

      + +

      SASL may be used with PLAINTEXT or SSL as the transport layer using the + security protocol SASL_PLAINTEXT or SASL_SSL respectively. If SASL_SSL is + used, then SSL must also be configured.

      + +
        +
      1. SASL mechanisms
        + Kafka supports the following SASL mechanisms: + +
        2. +
      2. SASL configuration for Kafka brokers
        +
          +
        1. Configure a SASL port in server.properties, by adding at least one of + SASL_PLAINTEXT or SASL_SSL to the listeners parameter, which + contains one or more comma-separated values: + 
              listeners=SASL_PLAINTEXT://host.name:port
          + If you are only configuring a SASL port (or if you want + the Kafka brokers to authenticate each other using SASL) then make sure + you set the same SASL protocol for inter-broker communication: + 
              security.inter.broker.protocol=SASL_PLAINTEXT (or SASL_SSL)
          2. +
        2. Select one or more supported mechanisms + to enable in the broker and follow the steps to configure SASL for the mechanism. + To enable multiple mechanisms in the broker, follow the steps + here.
        3. +
      3. SASL configuration for Kafka clients
        +

        SASL authentication is only supported for the new Java Kafka producer and + consumer, the older API is not supported.

        + +

        To configure SASL authentication on the clients, select a SASL + mechanism that is enabled in + the broker for client authentication and follow the steps to configure SASL + for the selected mechanism.

    5. Authentication using SASL/Kerberos

      @@ -502,6 +514,111 @@
    + +

  6. Authentication using SASL/SCRAM

    +

    Salted Challenge Response Authentication Mechanism (SCRAM) is a family of SASL mechanisms that + addresses the security concerns with traditional mechanisms that perform username/password authentication + like PLAIN and DIGEST-MD5. The mechanism is defined in RFC 5802. + Kafka supports SCRAM-SHA-256 and SCRAM-SHA-512 which + can be used with TLS to perform secure authentication. The username is used as the authenticated + Principal for configuration of ACLs etc. The default SCRAM implementation in Kafka + stores SCRAM credentials in Zookeeper and is suitable for use in Kafka installations where Zookeeper + is on a private network. Refer to Security Considerations + for more details.

    +
      +
    1. Creating SCRAM Credentials
      +

      The SCRAM implementation in Kafka uses Zookeeper as credential store. Credentials can be created in + Zookeeper using kafka-configs.sh. For each SCRAM mechanism enabled, credentials must be created + by adding a config with the mechanism name. Credentials for inter-broker communication must be created + before Kafka brokers are started. Client credentials may be created and updated dynamically and updated + credentials will be used to authenticate new connections.

      +

      Create SCRAM credentials for user alice with password alice-secret: + 

      +    bin/kafka-configs.sh --zookeeper localhost:2181 --alter --add-config 'SCRAM-SHA-256=[iterations=8192,password=alice-secret],SCRAM-SHA-512=[password=alice-secret]' --entity-type users --entity-name alice
+
      +

      The default iteration count of 4096 is used if iterations are not specified. A random salt is created + and the SCRAM identity consisting of salt, iterations, StoredKey and ServerKey are stored in Zookeeper. + See RFC 5802 for details on SCRAM identity and the individual fields. +

      The following examples also require a user admin for inter-broker communication which can be created using: + 

      +    bin/kafka-configs.sh --zookeeper localhost:2181 --alter --add-config 'SCRAM-SHA-256=[password=admin-secret],SCRAM-SHA-512=[password=admin-secret]' --entity-type users --entity-name admin
+
      +

      Existing credentials may be listed using the --describe option: + 

      +   bin/kafka-configs.sh --zookeeper localhost:2181 --describe --entity-type users --entity-name alice
+
      +

      Credentials may be deleted for one or more SCRAM mechanisms using the --delete option: + 

      +   bin/kafka-configs.sh --zookeeper localhost:2181 --alter --delete-config 'SCRAM-SHA-512' --entity-type users --entity-name alice
+
      +
      2. +
    2. Configuring Kafka Brokers
      +
        +
      1. Add a suitably modified JAAS file similar to the one below to each Kafka broker's config directory, let's call it kafka_server_jaas.conf for this example: + 
        +    KafkaServer {
+        org.apache.kafka.common.security.scram.ScramLoginModule required
+        username="admin"
+        password="admin-secret"
+    };
        + The properties username and password in the KafkaServer section are used by + the broker to initiate connections to other brokers. In this example, admin is the user for + inter-broker communication.
        2. +
      2. Pass the JAAS config file location as JVM parameter to each Kafka broker: + 
            -Djava.security.auth.login.config=/etc/kafka/kafka_server_jaas.conf
        3. +
      3. Configure SASL port and SASL mechanisms in server.properties as described here. For example: + 
        +    listeners=SASL_SSL://host.name:port
+    security.inter.broker.protocol=SASL_SSL
+    sasl.mechanism.inter.broker.protocol=SCRAM-SHA-256 (or SCRAM-SHA-512)
+    sasl.enabled.mechanisms=SCRAM-SHA-256 (or SCRAM-SHA-512)
        4. +
      +
      3. + +
    3. Configuring Kafka Clients
      + To configure SASL authentication on the clients: +
        +
      1. 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 SCRAM mechanisms: + 
        +   sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \
+        username="alice" \
+        password="alice-secret";
        + +

        The options username and password are used by clients to configure + the user for client connections. In this example, clients connect to the broker as user alice. + Different clients within a JVM may connect as different users by specifying different user names + and passwords in sasl.jaas.config.

        + +

        JAAS configuration for clients may alternatively be specified as a JVM parameter similar to brokers + as described here. Clients use the login section named + KafkaClient. This option allows only one user for all client connections from a JVM.

        2. + +
      2. Configure the following properties in producer.properties or consumer.properties: + 
        +    security.protocol=SASL_SSL
+    sasl.mechanism=SCRAM-SHA-256 (or SCRAM-SHA-512)
        3. +
      +
      4. +
    4. Security Considerations for SASL/SCRAM
      +
        +
      • The default implementation of SASL/SCRAM in Kafka stores SCRAM credentials in Zookeeper. This + is suitable for production use in installations where Zookeeper is secure and on a private network.
        • +
      • Kafka supports only the strong hash functions SHA-256 and SHA-512 with a minimum iteration count + of 4096. Strong hash functions combined with strong passwords and high iteration counts protect + against brute force attacks if Zookeeper security is compromised.
        • +
      • SCRAM should be used only with TLS-encryption to prevent interception of SCRAM exchanges. This + protects against dictionary or brute force attacks and against impersonation if Zookeeper is compromised.
        • +
      • The default SASL/SCRAM implementation may be overridden using custom login modules in installations + where Zookeeper is not secure. See here for details.
        • +
      • For more details on security considerations, refer to + RFC 5802. +
      +
      5. +
    +
    7. +

  7. Enabling multiple SASL mechanisms in a broker

    1. Specify configuration for the login modules of all enabled mechanisms in the KafkaServer section of the JAAS config file. For example: @@ -519,12 +636,14 @@ user_admin="admin-secret" user_alice="alice-secret"; };
      2. -
    2. Enable the SASL mechanisms in server.properties: 
          sasl.enabled.mechanisms=GSSAPI,PLAIN
      3. +
    3. Enable the SASL mechanisms in server.properties: 
          sasl.enabled.mechanisms=GSSAPI,PLAIN,SCRAM-SHA-256,SCRAM-SHA-512
    4. Specify the SASL security protocol and mechanism for inter-broker communication in server.properties if required: - 
          security.inter.broker.protocol=SASL_PLAINTEXT (or SASL_SSL)
-        sasl.mechanism.inter.broker.protocol=GSSAPI (or PLAIN)
      5. -
    5. Follow the mechanism-specific steps in GSSAPI (Kerberos) - and PLAIN to configure SASL for the enabled mechanisms.
      6. + 
      +    security.inter.broker.protocol=SASL_PLAINTEXT (or SASL_SSL)
+    sasl.mechanism.inter.broker.protocol=GSSAPI (or one of the other enabled mechanisms)
      +
    6. Follow the mechanism-specific steps in GSSAPI (Kerberos), + PLAIN and SCRAM + to configure SASL for the enabled mechanisms.

  8. Modifying SASL mechanism in a Running Cluster