8.6. Visibility Labels

This feature provides cell level security with labeled visibility for the cells. Cells can be associated with a visibility expression. The visibility expression can contain labels joined with logical expressions '&', '|' and '!'. Also using '(', ')' one can specify the precedence order. For example, consider the label set { confidential, secret, topsecret, probationary }, where the first three are sensitivity classifications and the last describes if an employee is probationary or not. If a cell is stored with this visibility expression: ( secret | topsecret ) & !probationary

Then any user associated with the secret or topsecret label will be able to view the cell, as long as the user is not also associated with the probationary label. Furthermore, any user only associated with the confidential label, whether probationary or not, will not see the cell or even know of its existence.

Visibility expressions like the above can be added when storing or mutating a cell using the API,

Mutation#setCellVisibility(new CellVisibility(String labelExpession));

Where the labelExpression could be '( secret | topsecret ) & !probationary'

We build the user's label set in the RPC context when a request is first received by the HBase RegionServer. How users are associated with labels is pluggable. The default plugin passes through labels specified in Authorizations added to the Get or Scan and checks those against the calling user's authenticated labels list. When client passes some labels for which the user is not authenticated, this default algorithm will drop those. One can pass a subset of user authenticated labels via the Scan/Get authorizations.

Get#setAuthorizations(new Authorizations(String,...));

Scan#setAuthorizations(new Authorizations(String,...));

8.6.1. Visibility Label Administration

There are new client side Java APIs and shell commands for performing visibility labels administrative actions. Only the HBase super user is authorized to perform these operations. Adding Labels

A set of labels can be added to the system either by using the Java API

VisibilityClient#addLabels(Configuration conf, final String[] labels)

Or by using the shell command

add_labels [label1, label2]

Valid label can include alphanumeric characters and characters '-', '_', ':', '.' and '/' User Label Association

A set of labels can be associated with a user by using the API

VisibilityClient#setAuths(Configuration conf, final String[] auths, final String user)

Or by using the shell command

set_auths user,[label1, label2].

Labels can be disassociated from a user using API

VisibilityClient#clearAuths(Configuration conf, final String[] auths, final String user)

Or by using shell command

clear_auths user,[label1, label2]

One can use the API VisibilityClient#getAuths(Configuration conf, final String user) or get_auths shell command to get the list of labels associated for a given user. The labels and user auths information will be stored in the system table "labels".

8.6.2. Server Side Configuration

HBase stores cell level labels as cell tags. HFile version 3 adds the cell tags support. Be sure to use HFile version 3 by setting this property in every server site configuration file:


You will also need to make sure the VisibilityController coprocessor is active on every table to protect by adding it to the list of system coprocessors in the server site configuration files:


As said above, finding out labels authenticated for a given get/scan request is a pluggable algorithm. A custom implementation can be plugged in using the property hbase.regionserver.scan.visibility.label.generator.class. The default implementation class is org.apache.hadoop.hbase.security.visibility.DefaultScanLabelGenerator. One can configure a set of ScanLabelGenerators to be used by the system. For this, a comma separated set of implementation class names to be configured.

Visibility Labels and Replication

By default, visibility labels are lost on replication. To change this behavior, see Preserving Tags During Replication.

comments powered by Disqus