This is the documentation for CDH 4.6.0.
Documentation for other versions is available at Cloudera Documentation.

Configuring HBase Authentication

Step 1: Configure HBase Servers to Authenticate with a Secure HDFS Cluster

To configure HBase servers to authenticate with a secure HDFS cluster, you must do the following tasks:

  • Enable HBase Authentication
  • Configure HBase's Kerberos Principals

Enabling HBase Authentication

To enable HBase Authentication, you must do the following two steps:

  1. On every HBase server host (Master or Region Server), add the following properties to the hbase-site.xml configuration file:
     
    <property>
        <name>hbase.security.authentication</name>
        <value>kerberos</value> 
    </property> 
    <property>
         <name>hbase.rpc.engine</name>
         <value>org.apache.hadoop.hbase.ipc.SecureRpcEngine</value>
    </property>
  2. On every HBase client host, add the same properties to the hbase-site.xml configuration file:
     
    <property>
        <name>hbase.security.authentication</name>
        <value>kerberos</value> 
    </property> 
    <property>
         <name>hbase.rpc.engine</name>
         <value>org.apache.hadoop.hbase.ipc.SecureRpcEngine</value>
    </property>

Configuring HBase's Kerberos Principals

In order to run HBase on a secure HDFS cluster, HBase must authenticate itself to the HDFS services. HBase acts as a Kerberos principal and needs Kerberos credentials to interact with the Kerberos-enabled HDFS daemons. Authenticating a service can be done using a keytab file. This file contains a key which allows the service to authenticate to the Kerberos Key Distribution Center (KDC).

To configure HBase's Kerberos principals:

  1. Create a service principal for the HBase server using the syntax: hbase/<fully.qualified.domain.name>@<YOUR-REALM>. This principal is used to authenticate the HBase server with the HDFS services. Cloudera recommends using hbase as the username portion of this principal.
    kadmin: addprinc -randkey hbase/fully.qualified.domain.name@YOUR-REALM.COM

    where: fully.qualified.domain.name is the host where the HBase server is running YOUR-REALM is the name of your Kerberos realm

  2. Create a keytab file for the HBase server.
    $ kadmin
    kadmin: xst -k hbase.keytab hbase/fully.qualified.domain.name
  3. Copy the hbase.keytab file to the /etc/hbase/conf directory on the HBase server host. The owner of the hbase.keytab file should be the hbase user and the file should have owner-only read permissions. That is, assign the file 0600 permissions and make it owned by hbase:hbase.
    -r--------  1 hbase   hbase     1343 2012-01-09 10:39  hbase.keytab
  4. To test that the keytab file was created properly, try to obtain Kerberos credentials as the HBase principal using only the keytab file. Substitute your fully.qualified.domain.name and realm in the following command:
    $ kinit -k -t /etc/hbase/conf/hbase.keytab hbase/fully.qualified.domain.name@YOUR-REALM.COM
  5. In the /etc/hbase/conf/hbase-site.xml configuration file on all of your cluster hosts running the HBase daemon, add the following lines:
    <property> 
      <name>hbase.regionserver.kerberos.principal</name> 
      <value>hbase/_HOST@YOUR-REALM.COM</value> 
    </property> 
    
    <property> 
      <name>hbase.regionserver.keytab.file</name> 
      <value>/etc/hbase/conf/hbase.keytab</value> 
    </property>
    
    <property> 
      <name>hbase.master.kerberos.principal</name> 
      <value>hbase/_HOST@YOUR-REALM.COM</value> 
    </property> 
    
    <property> 
    <name>hbase.master.keytab.file</name> 
    <value>/etc/hbase/conf/hbase.keytab</value> 
    </property>
      Important:

    Make sure you change the /etc/hbase/conf/hbase-site.xml configuration file on all of your cluster hosts that are running the HBase daemon.

Step 2: Configure HBase Servers and Clients to Authenticate with a Secure ZooKeeper

In order to run a secure HBase, you must also use a secure ZooKeeper. To use your secure ZooKeeper, each HBase host machine (Master, Region Server, and client) must have a principal that allows it to authenticate with your secure ZooKeeper ensemble. Note, this HBase section assumes that your secure ZooKeeper is already configured according to the instructions in the ZooKeeper Security Configuration section and not managed by HBase.

This HBase section also assumes that you have successfully completed the previous steps, and already have a principal and keytab file created and in place for every HBase server and client.

Configure HBase JVMs (all Masters, Region Servers, and clients) to use JAAS

  1. On each host, set up a Java Authentication and Authorization Service (JAAS) by creating a /etc/hbase/conf/zk-jaas.conf file that contains the following:
       Client {
          com.sun.security.auth.module.Krb5LoginModule required
          useKeyTab=true
          useTicketCache=false
          keyTab="/etc/hbase/conf/hbase.keytab"
          principal="hbase/fully.qualified.domain.name@<YOUR-REALM>";
       };
  2. Modify the hbase-env.sh file on HBase server and client hosts to include the following:
       export HBASE_OPTS="$HBASE_OPTS -Djava.security.auth.login.config=/etc/hbase/conf/zk-jaas.conf"
       export HBASE_MANAGES_ZK=false

Configure the HBase Servers (Masters and Region Servers) to use Authentication to connect to ZooKeeper

  1. Update your hbase-site.xml on each HBase server host with the following properties:
    <configuration>
       <property>
          <name>hbase.zookeeper.quorum</name>
          <value>$ZK_NODES</value>
       </property>
       <property>
          <name>hbase.cluster.distributed</name>
          <value>true</value>
       </property>
    </configuration>

    where $ZK_NODES is the comma-separated list of hostnames of the ZooKeeper Quorum hosts that you configured according to the instructions in ZooKeeper Security Configuration.

  2. Add the following lines to the ZooKeeper configuration file zoo.cfg:
    kerberos.removeHostFromPrincipal=true
    kerberos.removeRealmFromPrincipal=true

Start HBase

If the configuration worked, you should see something similar to the following in the HBase Master and Region Server logs when you start the cluster:

INFO zookeeper.ZooKeeper: Initiating client connection, connectString=ZK_QUORUM_SERVER:2181 sessionTimeout=180000 watcher=master:60000
INFO zookeeper.ClientCnxn: Opening socket connection to server /ZK_QUORUM_SERVER:2181
INFO zookeeper.RecoverableZooKeeper: The identifier of this process is PID@ZK_QUORUM_SERVER
INFO zookeeper.Login: successfully logged in.
INFO client.ZooKeeperSaslClient: Client will use GSSAPI as SASL mechanism.
INFO zookeeper.Login: TGT refresh thread started.
INFO zookeeper.ClientCnxn: Socket connection established to ZK_QUORUM_SERVER:2181, initiating session
INFO zookeeper.Login: TGT valid starting at:        Sun Apr 08 22:43:59 UTC 2012
INFO zookeeper.Login: TGT expires:                  Mon Apr 09 22:43:59 UTC 2012
INFO zookeeper.Login: TGT refresh sleeping until: Mon Apr 09 18:30:37 UTC 2012
INFO zookeeper.ClientCnxn: Session establishment complete on server ZK_QUORUM_SERVER:2181, sessionid = 0x134106594320000, negotiated timeout = 180000