Authentication using SASL

Bookies support client authentication via SASL. Currently we only support GSSAPI (Kerberos). We will start
with a general description of how to configure SASL for bookies, clients and autorecovery daemons, followed
by mechanism-specific details and wrap up with some operational details.

SASL configuration for Bookies

Select the mechanisms to enable in the bookies. GSSAPI is the only mechanism currently supported by BookKeeper.

Add a JAAS config file for the selected mechanisms as described in the examples for setting up GSSAPI (Kerberos).

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

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.

Important Notes

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.

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.

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).

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).

SASL configuration for Clients

To configure SASL authentication on the clients:

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

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

Authentication using SASL/Kerberos

Prerequisites

Kerberos

If your organization is already using a Kerberos server (for example, by using Active Directory), there is no need to
install a new server just for BookKeeper. Otherwise you will need to install one, your Linux vendor likely has packages
for Kerberos and a short guide on how to install and configure it (Ubuntu,
Redhat).
Note that if you are using Oracle Java, you will need to download JCE policy files for your Java version and copy them to $JAVA_HOME/jre/lib/security.

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:

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.

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

Enable SASL authentication plugin in the bookies by setting following parameters.

bookieAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLBookieAuthProviderFactory
# if you run `autorecovery` along with bookiesclientAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLClientProviderFactory

Configuring Clients

To configure SASL authentication on the clients:

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):