solr/solr-ref-guide/src/hadoop-authentication-plugin.adoc

= Hadoop Authentication Plugin
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

The Hadoop authentication plugin enables Solr to use the https://hadoop.apache.org/docs/stable/hadoop-auth/index.html[Hadoop authentication library] for securing Solr nodes.

This authentication plugin is a thin wrapper that delegates all functionality to the Hadoop authentication library. All configuration parameters for the library are passed through the plugin.

This plugin can be particularly useful in leveraging an extended set of features or newly available features in the Hadoop authentication library.

Please note that the version of Hadoop library used by Solr is upgraded periodically. While Solr will ensure the stability and backwards compatibility of the structure of the plugin configuration (viz., the parameter names of this plugin), the values of these parameters may change based on the version of Hadoop library. Please review the Hadoop documentation for the version used by your Solr installation for more details.

For some of the authentication schemes (e.g., Kerberos), Solr provides a native implementation of authentication plugin. If you require a more stable setup, in terms of configuration, ability to perform rolling upgrades, backward compatibility, etc., you should consider using such plugin. Please review the section <<authentication-and-authorization-plugins.adoc#,Authentication and Authorization Plugins>> for an overview of authentication plugin options in Solr.

There are two plugin classes:

* `HadoopAuthPlugin`: This can be used with standalone Solr as well as SolrCloud with <<authentication-and-authorization-plugins.adoc#securing-inter-node-requests,PKI authentication>> for internode communication.
* `ConfigurableInternodeAuthHadoopPlugin`: This is an extension of HadoopAuthPlugin that allows you to configure the authentication scheme for internode communication.

[TIP]
====
For most SolrCloud or standalone Solr setups, the `HadoopAuthPlugin` should suffice.
====

== Plugin Configuration

`class`::
Should be either `solr.HadoopAuthPlugin` or `solr.ConfigurableInternodeAuthHadoopPlugin`. This parameter is required.

`type`::
The type of authentication scheme to be configured. See https://hadoop.apache.org/docs/stable/hadoop-auth/Configuration.html[configuration] options. This parameter is required.

`sysPropPrefix`::
The prefix to be used to define the Java system property for configuring the authentication mechanism. This property is required.
+
The name of the Java system property is defined by appending the configuration parameter name to this prefix value. For example, if the prefix is `solr` then the Java system property `solr.kerberos.principal` defines the value of configuration parameter `kerberos.principal`.

`authConfigs`::
Configuration parameters required by the authentication scheme defined by the type property. This property is required. For more details, see https://hadoop.apache.org/docs/stable/hadoop-auth/Configuration.html[Hadoop configuration] options.

`defaultConfigs`::
Default values for the configuration parameters specified by the `authConfigs` property. The default values are specified as a collection of key-value pairs (i.e., `"property-name": "default_value"`).

`enableDelegationToken`::
If `true`, the delegation tokens functionality will be enabled.

`initKerberosZk`::
For enabling initialization of kerberos before connecting to ZooKeeper (if applicable).

`proxyUserConfigs`::
Configures proxy users for the underlying Hadoop authentication mechanism. This configuration is expressed as a collection of key-value pairs (i.e., `"property-name": "default_value"`).

`clientBuilderFactory`:: No |
The `HttpClientBuilderFactory` implementation used for the Solr internal communication. Only applicable for `ConfigurableInternodeAuthHadoopPlugin`.

== Example Configurations

=== Kerberos Authentication using Hadoop Authentication Plugin

This example lets you configure Solr to use Kerberos Authentication, similar to how you would use the <<kerberos-authentication-plugin.adoc#,Kerberos Authentication Plugin>>.

After consulting the Hadoop authentication library's documentation, you can supply per host configuration parameters using the `solr.*` prefix. As an example, the Hadoop authentication library expects a parameter `kerberos.principal`, which can be supplied as a system property named `solr.kerberos.principal` when starting a Solr node. Refer to the section <<kerberos-authentication-plugin.adoc#,Kerberos Authentication Plugin>> for other typical configuration parameters.

Please note that this example uses `ConfigurableInternodeAuthHadoopPlugin`, and hence you must provide the `clientBuilderFactory` implementation. As a result, all internode communication will use the Kerberos mechanism, instead of PKI authentication.

This configuration assumes that your servers are using the `solr` principal, and will be allowed to impersonate any other user with requests coming from any other host. For additional security, consider setting the host list to match your cluster nodes. The Hadoop https://hadoop.apache.org/docs/r3.2.2/hadoop-project-dist/hadoop-common/Superusers.html[proxy users] documentation contains more detail about available configuration options.

To setup this plugin, use the following in your `security.json` file.

[source,json]
----
{
    "authentication": {
        "class": "solr.ConfigurableInternodeAuthHadoopPlugin",
        "sysPropPrefix": "solr.",
        "type": "kerberos",
        "clientBuilderFactory": "org.apache.solr.client.solrj.impl.Krb5HttpClientBuilder",
        "initKerberosZk": "true",
        "enableDelegationToken": "true",
        "authConfigs": [
            "kerberos.principal",
            "kerberos.keytab",
            "kerberos.name.rules"
        ],
        "defaultConfigs": {
        },
        "proxyUserConfigs": {
          "proxyuser.solr.hosts": "*",
          "proxyuser.solr.groups": "*"
        }
    }
}
----

[WARNING]
For the `ConfigurableInternodeAuthHadoopPlugin`, user credential proxying relies on delegation token support. Without it, forwarded requests will authenticate as Solr server credentials instead of real-user credentials, and likely allowing authenticated-but-unauthorized users to query and index documents into your collections.

=== Simple Authentication with Delegation Tokens

Similar to the previous example, this is an example of setting up a Solr cluster that uses delegation tokens. Refer to the parameters in the Hadoop authentication library's https://hadoop.apache.org/docs/stable/hadoop-auth/Configuration.html[documentation] or refer to the section <<kerberos-authentication-plugin.adoc#,Kerberos Authentication Plugin>> for further details. Please note that this example does not use Kerberos and the requests made to Solr must contain valid delegation tokens.

To setup this plugin, use the following in your `security.json` file.

[source,json]
----
{
    "authentication": {
        "class": "solr.HadoopAuthPlugin",
        "sysPropPrefix": "solr.",
        "type": "simple",
        "enableDelegationToken":"true",
        "authConfigs": [
            "delegation-token.token-kind",
            "delegation-token.update-interval.sec",
            "delegation-token.max-lifetime.sec",
            "delegation-token.renewal-interval.sec",
            "delegation-token.removal-scan-interval.sec",
            "cookie.domain",
            "signer.secret.provider",
            "zk-dt-secret-manager.enable",
            "zk-dt-secret-manager.znodeWorkingPath",
            "signer.secret.provider.zookeeper.path"
        ],
        "defaultConfigs": {
            "delegation-token.token-kind": "solr-dt",
            "signer.secret.provider": "zookeeper",
            "zk-dt-secret-manager.enable": "true",
            "token.validity": "36000",
            "zk-dt-secret-manager.znodeWorkingPath": "solr/security/zkdtsm",
            "signer.secret.provider.zookeeper.path": "/token",
            "cookie.domain": "127.0.0.1"
        }
    }
}
----