Sentry uses a role-based privilege model. A role is a set of rules for accessing a given Solr collection. Access to each collection is governed by privileges: Query, Update, or All (*).

collection=logs->action=Query

engineer_role = collection=hive_logs->action=Query, collection=hbase_logs->action=Query, collection=current_bugs->action=Update

• A user is an entity that is permitted by the Kerberos authentication system to access the Search service.
• A group connects the authentication system with the authorization system. It is a set of one or more users who have been granted one or more authorization roles. Sentry allows a set of roles to be configured for a group.
• A configured group provider determines a user’s affiliation with a group. The current release supports HDFS-backed groups and locally configured groups. For example,

  dev_ops = dev_role, ops_role

Here the group dev_ops is granted the roles dev_role and ops_role. The members of this group can complete searches that are allowed by these roles.

This release of Sentry stores the configuration as well as privilege policies in files. The sentry-site.xml file contains configuration options such as privilege policy file location. The Policy File contains the privileges and groups. It has a .ini file format and should be stored on HDFS.

Sentry is automatically installed when you install Cloudera Search for CDH or Cloudera Search 1.1.0 or later.

The sections that follow contain notes on creating and maintaining the policy file.

  Warning: An invalid configuration disables all authorization while logging an exception.

This section provides a sample configuration.

  Note: Sentry with CDH Search does not support multiple policy files. Other implementations of Sentry such as Sentry for Hive do support different policy files for different databases, but Sentry for CDH Search has no such support for multiple policies.

SOLR_AUTHORIZATION_SENTRY_SITE=/location/to/sentry-site.xml
SOLR_AUTHORIZATION_SUPERUSER=solr

To enable sentry collection-level authorization checking on a new collection, the instancedir for the collection must use a modified version of solrconfig.xml with Sentry integration. The command solrctl instancedir --generate generates two versions of solrconfig.xml: the standard solrconfig.xml without sentry integration, and the sentry-integrated version called solrconfig.xml.secure. To use the sentry-integrated version, replace solrconfig.xml with solrconfig.xml.secure before creating the instancedir.

If you have an existing collection using the standard solrconfig.xml called "foo" and an instancedir of the same name, perform the following steps:

# generate a fresh instancedir
solrctl instancedir --generate foosecure
# download the existing instancedir from ZK into subdirectory "foo"
solrctl instancedir --get foo foo
# replace the existing solrconfig.xml with the sentry-enabled one
cp foosecure/conf/solrconfig.xml.secure foo/conf/solrconfig.xml
# update the instancedir in ZK
solrctl instancedir --update foo foo
# reload the collection
solrctl collection --reload foo

If you have an existing collection using a version of solrconfig.xml that you have modified, contact Support for assistance.

For role-based access control of a collection, an administrator modifies a Sentry role so it has query, update, or administrative access, as described above.

Collection-level authorization is useful when the access control requirements for the documents in the collection are the same, but users may want to restrict access to a subset of documents in a collection. This finer-grained restriction could be achieved by defining separate collections for each subset, but this is difficult to manage, requires duplicate documents for each collection, and requires that these documents be kept in sync.

Document-level access control solves this issue by associating authorization tokens with each document in the collection. This enables granting Sentry roles access to sets of documents in a collection.

Document-Level Security Model

Document-level security depends on a chain of relationships between users, groups, roles, and documents.

• Users are assigned to groups.
• Groups are assigned to roles.
• Roles are stored as "authorization tokens" in a specified field in the documents.

Document-level security supports restricting which documents can be viewed by which users. Access is provided by adding roles as "authorization tokens" to a specified document field. Conversely, access is implicitly denied by omitting roles from the specified field. In other words, in a document-level security enabled environment, a user might submit a query that matches a document; if the user is not part of a group that has a role has been granted access to the document, the result is not returned.

For example, Alice might belong to the administrators group. The administrators group may belong to the doc-mgmt role. A document could be ingested and the doc-mgmt role could be added at ingest time. In such a case, if Alice submitted a query that matched the document, Search would return the document, since Alice is then allowed to see any document with the "doc-mgmt" authorization token.

Similarly, Bob might belong to the guests group. The guests group may belong to the public-browser role. If Bob tried the same query as Alice, but the document did not have the public-browser role, Search would not return the result because Bob does not belong to a group that is associated with a role that has access.

Note that collection-level authorization rules still apply, if enabled. Even if Alice is able to view a document given document-level authorization rules, if she is not allowed to query the collection, the query will fail.

Roles are typically added to documents when those documents are ingested, either via the standard Solr APIs or, if using morphlines, the setValues morphline command.

Enabling Document-Level Security

Cloudera Search supports document-level security in Search for CDH 5.1 and later. Document-level security is disabled by default, so the first step in using document-level security is to enable the feature by modifying the solrconfig.xml.secure file. Remember to replace the solrconfig.xml with this file, as described in Enabling Sentry for Cloudera Search in CDH 5 above.

To enable document-level security, change solrconfig.xml.secure. The default file contents are as follows:

<searchComponent name="queryDocAuthorization">
    <!-- Set to true to enabled document-level authorization -->

    <bool name="enabled">false</bool>


    <!-- Field where the auth tokens are stored in the document -->
    <str name="sentryAuthField">sentry_auth</str>


    <!-- Auth token defined to allow any role to access the document.
         Uncomment to enable. -->

    <!--<str name="allRolesToken">*</str>-->

</searchComponent>

• The enabled Boolean determines whether document-level authorization is enabled. To enable document level security, change this setting to true.
• The sentryAuthField string specifies the name of the field that is used for storing authorization information. You can use the default setting of sentry_auth or you can specify some other string that you will use for assigning values on ingest.
    Note: This field must exist as an explicit or dynamic field in the schema. sentry_auth exists in the default schema.xml.
• The allRolesToken string represents a special token defined to allow any role access to the document. By default, this feature is disabled. To enable this feature, uncomment the specification and specify the token. This token should be different from the name of any sentry role to avoid collision. By default it is "*". This feature is useful when first configuring document level security or it can be useful in granting all roles access to a document when the set of roles may change. See the following Best Practices section for additional information.

org.apache.lucene.search.BooleanQuery$TooManyClauses: maxClauseCount is set to 1024

<maxBooleanClauses>2048</maxBooleanClauses>

Secure Impersonation is a feature that allows a user to make requests as another user in a secure way. For example, to allow the following impersonations:

• User "hue" can make requests as any user from any host.
• User "foo" can make requests as any member of group "bar", from "host1" or "host2".
  Configure the following properties in /etc/default/solr:

  SOLR_SECURITY_ALLOWED_PROXYUSERS=hue,foo
  SOLR_SECURITY_PROXYUSER_hue_HOSTS=*
  SOLR_SECURITY_PROXYUSER_hue_GROUPS=*
  SOLR_SECURITY_PROXYUSER_foo_HOSTS=host1,host2
  SOLR_SECURITY_PROXYUSER_foo_GROUPS=bar

SOLR_SECURITY_ALLOWED_PROXYUSERS lists all of the users allowed to impersonate. For a user x in SOLR_SECURITY_ALLOWED_PROXYUSERS, SOLR_SECURITY_PROXYUSER_x_HOSTS list the hosts x is allowed to connect from in order to impersonate, and SOLR_SECURITY_PROXYUSERS_x_GROUPS lists the groups that the users is allowed to impersonate members of. Both GROUPS and HOSTS support the wildcard * and both GROUPS and HOSTS must be defined for a specific user.

  Note: Cloudera Manager has its own management of secure impersonation for Hue. To add additional users for Secure Impersonation, use the environment variable safety value for Solr to set the environment variables as above. Be sure to include "hue" in SOLR_SECURITY_ALLOWED_PROXYUSERS if you want to use secure impersonation for hue.

The tables below refer to the request handlers defined in the generated solrconfig.xml.secure. If you are not using this configuration file, the below may not apply.

admin is a special collection in sentry used to represent administrative actions. A non-administrative request may only require privileges on the collection on which the request is being performed. This is called collection1 in this appendix. An administrative request may require privileges on both the admin collection and collection1. This is denoted as admin, collection1 in the tables below.

Table 2. Privilege table for collections admin actions

Collection Action	Required Privilege	Collections that Require Privilege
create	UPDATE	admin, collection1
delete	UPDATE	admin, collection1
reload	UPDATE	admin, collection1
createAlias	UPDATE	admin, collection1   Note: "collection1" here refers to the name of the alias, not the underlying collection(s). For example, http://YOUR-HOST:8983/ solr/admin/collections?action= CREATEALIAS&name=collection1 &collections=underlyingCollection
deleteAlias	UPDATE	admin, collection1   Note: "collection1" here refers to the name of the alias, not the underlying collection(s). For example, http://YOUR-HOST:8983/ solr/admin/collections?action= DELETEALIAS&name=collection1
syncShard	UPDATE	admin, collection1
splitShard	UPDATE	admin, collection1
deleteShard	UPDATE	admin, collection1