Configuring Authentication, Authorization and Audit Logging

Solr has security frameworks for supporting authentication, authorization and auditing of users. This allows for verifying a user’s identity and for restricting access to resources in a Solr cluster.

Solr includes some plugins out of the box, and additional plugins can be developed using the authentication, authorization and audit logging frameworks described below.

All authentication, authorization and audit logging plugins can work with Solr whether they are running in SolrCloud mode or standalone mode. All related configuration, including users and permission rules, are stored in a file named security.json. When using Solr in standalone mode, this file must be in the $SOLR_HOME directory (usually server/solr). When using SolrCloud, this file must be located in ZooKeeper.

The following section describes how to enable plugins with security.json and place them in the proper locations for your mode of operation.

Enable Plugins with security.json

All of the information required to initialize either type of security plugin is stored in a security.json file. This file contains 3 sections, one each for authentication, authorization, and audit logging.

Sample security.json
{
  "authentication" : {
    "class": "class.that.implements.authentication"
  },
  "authorization": {
    "class": "class.that.implements.authorization"
  },
  "auditlogging": {
    "class": "class.that.implements.auditlogging"
  }
}

The /security.json file needs to be in the proper location before a Solr instance comes up so Solr starts with the security plugin enabled. See the section Using security.json with Solr below for information on how to do this.

Depending on the plugin(s) in use, other information will be stored in security.json such as user information or rules to create roles and permissions. This information is added through the APIs for each plugin provided by Solr, or, in the case of a custom plugin, the approach designed by you.

Here is a more detailed security.json example. In this, the Basic authentication and rule-based authorization plugins are enabled, and some data has been added:

{
"authentication":{
   "class":"solr.BasicAuthPlugin",
   "credentials":{"solr":"IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="}
},
"authorization":{
   "class":"solr.RuleBasedAuthorizationPlugin",
   "permissions":[{"name":"security-edit",
      "role":"admin"}],
   "user-role":{"solr":"admin"}
}}

Using security.json with Solr

In SolrCloud Mode

While configuring Solr to use an authentication or authorization plugin, you will need to upload a security.json file to ZooKeeper. The following command writes the file as it uploads it - you could also upload a file that you have already created locally.

>server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181 -cmd put /security.json
  '{"authentication": {"class": "org.apache.solr.security.KerberosPlugin"}}'

Note that this example defines the KerberosPlugin for authentication. You will want to modify this section as appropriate for the plugin you are using.

This example also defines security.json on the command line, but you can also define a file locally and upload it to ZooKeeper.

If you have defined ZK_HOST in solr.in.sh/solr.in.cmd (see instructions) you can omit -z <zk host string> from the above command.

Whenever you use any security plugins and store security.json in ZooKeeper, we highly recommend that you implement access control in your ZooKeeper nodes. Information about how to enable this is available in the section ZooKeeper Access Control.

Once security.json has been uploaded to ZooKeeper, you should use the appropriate APIs for the plugins you’re using to update it. You can edit it manually, but you must take care to remove any version data so it will be properly updated across all ZooKeeper nodes. The version data is found at the end of the security.json file, and will appear as the letter "v" followed by a number, such as {"v":138}.

In Standalone Mode

When running Solr in standalone mode, you need to create the security.json file and put it in the $SOLR_HOME directory for your installation (this is the same place you have located solr.xml and is usually server/solr).

If you are using Legacy Scaling and Distribution, you will need to place security.json on each node of the cluster.

You can use the authentication and authorization APIs, but if you are using the legacy scaling model, you will need to make the same API requests on each node separately. You can also edit security.json by hand if you prefer.

Authentication

Authentication plugins help in securing the endpoints of Solr by authenticating incoming requests. A custom plugin can be implemented by extending the AuthenticationPlugin class.

An authentication plugin consists of two parts:

  1. Server-side component, which intercepts and authenticates incoming requests to Solr using a mechanism defined in the plugin, such as Kerberos, Basic Auth or others.
  2. Client-side component, i.e., an extension of HttpClientConfigurer, which enables a SolrJ client to make requests to a secure Solr instance using the authentication mechanism which the server understands.

Enabling an Authentication Plugin

  • Specify the authentication plugin in /security.json as in this example:

    {
  "authentication": {
    "class": "class.that.implements.authentication",
    "other_data" : "..."}
}

  • All of the content in the authentication block of security.json would be passed on as a map to the plugin during initialization.

  • An authentication plugin can also be used with a standalone Solr instance by passing in -DauthenticationPlugin=<plugin class name> during startup.

Currently available authentication plugins are:

Authorization

An authorization plugin can be written for Solr by extending the AuthorizationPlugin interface.

Enabling an Authorization Plugin

  • Make sure that the plugin implementation is in the classpath.

  • The plugin can then be initialized by specifying the same in security.json in the following manner:

{
  "authorization": {
    "class": "org.apache.solr.security.MockAuthorizationPlugin",
    "other_data" : "..."}
}

All of the content in the authorization block of security.json would be passed on as a map to the plugin during initialization.

Reloading the plugin isn’t yet supported and requires a restart of the Solr installation (meaning, the JVM should be restarted, not simply a core reload).

Currently available authorization plugins are:

Audit Logging

Audit logging plugins help you keep an audit trail of events happening in your Solr cluster. Audit logging may e.g., ship data to an external audit service. A custom plugin can be implemented by extending the AuditLoggerPlugin class.

Authenticating in the Admin UI

Whenever an authentication plugin is enabled, authentication is also required for all or some operations in the Admin UI. The Admin UI is an AngularJS application running inside your browser, and is treated as any other external client by Solr.

When authentication is required the Admin UI will presented you with a login dialogue. The authentication plugins currently supported by the Admin UI are:

If your plugin of choice is not supported, the Admin UI will still let you perform unrestricted operations, while for restricted operations you will need to interact with Solr by sending HTTP requests instead of through the graphical user interface of the Admin UI. All operations supported by Admin UI can be performed through Solr’s RESTful APIs.

Securing Inter-Node Requests

There are a lot of requests that originate from the Solr nodes itself. For example, requests from overseer to nodes, recovery threads, etc. We call these 'inter-node' request. Solr has a special built-in PKIAuthenticationPlugin (see below) that will always be available to secure inter-node traffic.

Each Authentication plugin may also decide to secure inter-node requests on its own. They may do this through the so-called HttpClientBuilder mechanism, or they may alternatively choose on a per-request basis whether to delegate to PKI or not by overriding a interceptInternodeRequest() method from the base class, where any HTTP headers can be set.

PKIAuthenticationPlugin

The PKIAuthenticationPlugin provides a built-in authentication mechanism where each Solr node is a super user and is fully trusted by other Solr nodes through the use of Public Key Infrastructure (PKI). Each Authentication plugn may choose to delegate all or some inter-node traffic to the PKI plugin.

For each outgoing request PKIAuthenticationPlugin adds a special header 'SolrAuth' which carries the timestamp and principal encrypted using the private key of that node. The public key is exposed through an API so that any node can read it whenever it needs it. Any node who gets the request with that header, would get the public key from the sender and decrypt the information. If it is able to decrypt the data, the request trusted. It is invalid if the timestamp is more than 5 secs old. This assumes that the clocks of different nodes in the cluster are synchronized. Only traffic from other Solr nodes registered with ZooKeeper is trusted.

The timeout is configurable through a system property called pkiauth.ttl. For example, if you wish to bump up the time-to-live to 10 seconds (10000 milliseconds), start each node with a property '-Dpkiauth.ttl=10000'.