1. Select the mechanisms to enable in the bookies. GSSAPI is the only mechanism currently supported by BookKeeper.
  2. Add a JAAS config file for the selected mechanisms as described in the examples for setting up GSSAPI (Kerberos).

  3. Pass the JAAS config file location as JVM parameter to each Bookie. For example:

  4. Enable SASL auth plugin in bookies, by setting bookieAuthProviderFactoryClass to org.apache.bookkeeper.sasl.SASLBookieAuthProviderFactory.

    1.  bookieAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLBookieAuthProviderFactory

  5. If you are running autorecovery along with bookies, then you want to enable SASL auth plugin for autorecovery, by setting clientAuthProviderFactoryClass to org.apache.bookkeeper.sasl.SASLClientProviderFactory.

    1.  clientAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLClientProviderFactory

  6. Follow the steps in to configure SASL.

Important Notes

  1. Bookie is a section name in the JAAS file used by each bookie. This section tells the bookie which principal to use and the location of the keytab where the principal is stored. It allows the bookie to login using the keytab specified in this section.
  2. Auditor is a section name in the JASS file used by autorecovery daemon (it can be co-run with bookies). This section tells the autorecovery daemon which principal to use and the location of the keytab where the principal is stored. It allows the bookie to login using the keytab specified in this section.
  3. The Client section is used to authenticate a SASL connection with ZooKeeper. It also allows the bookies to set ACLs on ZooKeeper nodes which locks these nodes down so that only the bookies can modify it. It is necessary to have the same primary name across all bookies. 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. 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).

To configure SASL authentication on the clients:

  1. Select a SASL mechanism for authentication and add a JAAS config file for the selected mechanism as described in the examples for setting up .

  2. Configure the following properties in bookkeeper ClientConfiguration:

Follow the steps in GSSAPI (Kerberos) to configure SASL for the selected mechanism.

Kerberos

Kerberos Principals

If you are using the organization’s Kerberos or Active Directory server, ask your Kerberos administrator for a principal for each Bookie in your cluster and for every operating system user that will access BookKeeper with Kerberos authentication (via clients and tools).

If you have installed your own Kerberos, you will need to create these principals yourself using the following commands:

  1. sudo /usr/sbin/kadmin.local -q 'addprinc -randkey bookkeeper/{hostname}@{REALM}'
  2. sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{keytabname}.keytab bookkeeper/{hostname}@{REALM}"
All hosts must be reachable using hostnames

It is a Kerberos requirement that all your hosts can be resolved with their FQDNs.

  1. Add a suitably modified JAAS file similar to the one below to each Bookie’s config directory, let’s call it bookie_jaas.conf for this example (note that each bookie should have its own keytab):

    1.  Bookie {
    2.      com.sun.security.auth.module.Krb5LoginModule required
    3.      useKeyTab=true
    4.      storeKey=true
    5.      keyTab="/etc/security/keytabs/bookie.keytab"
    6.      principal="bookkeeper/bk1.hostname.com@EXAMPLE.COM";
    7.  };
    8.  // ZooKeeper client authentication
    9.  Client {
    10.      com.sun.security.auth.module.Krb5LoginModule required
    11.      useKeyTab=true
    12.      storeKey=true
    13.      keyTab="/etc/security/keytabs/bookie.keytab"
    14.      principal="bookkeeper/bk1.hostname.com@EXAMPLE.COM";
    15.  };
    16.  // If you are running `autorecovery` along with bookies
    17.  Auditor {
    19.      storeKey=true
    20.      keyTab="/etc/security/keytabs/bookie.keytab"
    21.      principal="bookkeeper/bk1.hostname.com@EXAMPLE.COM";
    22.  };

    The Bookie section in the JAAS file tells the bookie which principal to use and the location of the keytab where this principal is stored. It allows the bookie to login using the keytab specified in this section. See notes for more details on Zookeeper’s SASL configuration.

  2. Pass the name of the JAAS file as a JVM parameter to each Bookie:

    1.  -Djava.security.auth.login.config=/etc/bookkeeper/bookie_jaas.conf

    You may also wish to specify the path to the krb5.conf file (see for more details):

  3. Make sure the keytabs configured in the JAAS file are readable by the operating system user who is starting the Bookies.

    1.  bookieAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLBookieAuthProviderFactory
    2.  # if you run `autorecovery` along with bookies
    3.  clientAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLClientProviderFactory

To configure SASL authentication on the clients:

  1. Clients will authenticate to the cluster with their own principal (usually with the same name as the user running the client), so obtain or create these principals as needed. Then create a JAAS file for each principal. The BookKeeper section describes how the clients like writers and readers can connect to the Bookies. The following is an example configuration for a client using a keytab (recommended for long-running processes):

    1.  BookKeeper {
    2.      com.sun.security.auth.module.Krb5LoginModule required
    3.      useKeyTab=true
    4.      storeKey=true
    5.      keyTab="/etc/security/keytabs/bookkeeper.keytab"
    6.      principal="bookkeeper-client-1@EXAMPLE.COM";
    7.  };

  2. Pass the name of the JAAS file as a JVM parameter to the client JVM:

    1.  -Djava.security.auth.login.config=/etc/bookkeeper/bookkeeper_jaas.conf

    You may also wish to specify the path to the krb5.conf file (see JDK’s Kerberos Requirements for more details).

  3. Make sure the keytabs configured in the bookkeeper_jaas.conf are readable by the operating system user who is starting bookkeeper client.

  4. Enable SASL authentication plugin in the client by setting following parameters.

    To enable SASL debug output, you can set sun.security.krb5.debug system property to .

    Next