solr/solr-ref-guide/modules/deployment-guide/pages/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 the Hadoop library.
Please review the Hadoop documentation for v{dep-version-hadoop} used by this version of Solr.

For some 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 one of these plugins.
Please review the section xref:authentication-and-authorization-plugins.adoc[] for an overview of authentication plugin options in Solr.

There are two plugin classes:

* `HadoopAuthPlugin`: This can be used with SolrCloud, user-managed, and single-node installations as well as SolrCloud with xref: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 installations, the `HadoopAuthPlugin` should suffice.
====

== Plugin Configuration

`class`::
+
[%autowidth,frame=none]
|===
s|Required |Default: none
|===
+
The plugin classname.
It should be either `solr.HadoopAuthPlugin` or `solr.ConfigurableInternodeAuthHadoopPlugin`.

`type`::
+
[%autowidth,frame=none]
|===
s|Required |Default: none
|===
+
The type of authentication scheme to be configured.
See the Hadoop https://hadoop.apache.org/docs/stable/hadoop-auth/Configuration.html[configuration options].

`sysPropPrefix`::
+
[%autowidth,frame=none]
|===
s|Required |Default: none
|===
+
The prefix to use to define a Java system property for configuring the authentication mechanism.
+
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`::
+
[%autowidth,frame=none]
|===
s|Required |Default: none
|===
+
Configuration parameters required by the authentication scheme defined by the type property.
For more details, see the Hadoop https://hadoop.apache.org/docs/stable/hadoop-auth/Configuration.html[configuration options].

`defaultConfigs`::
+
[%autowidth,frame=none]
|===
|Optional |Default: none
|===
+
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`::
+
[%autowidth,frame=none]
|===
|Optional |Default: none
|===
+
If `true`, delegation tokens functionality will be enabled.
See the section <<Simple Authentication with Delegation Tokens>> for an example.

`initKerberosZk`::
+
[%autowidth,frame=none]
|===
|Optional |Default: none
|===
+
If `true`, Kerberos will be initialized before connecting to ZooKeeper (if applicable).

`proxyUserConfigs`::
+
[%autowidth,frame=none]
|===
|Optional |Default: none
|===
+
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`::
+
[%autowidth,frame=none]
|===
|Optional |Default: none
|===
+
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 xref:kerberos-authentication-plugin.adoc[].

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 xref:kerberos-authentication-plugin.adoc[] for other typical configuration parameters.

The example below 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/stable/hadoop-project-dist/hadoop-common/Superusers.html[proxy users documentation] contains more detail about available configuration options.

[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 https://hadoop.apache.org/docs/stable/hadoop-auth/Configuration.html[authentication library's documentation] or refer to the section xref:kerberos-authentication-plugin.adoc[] for further details.

Please note that this example does not use Kerberos and the requests made to Solr must contain valid delegation tokens.

[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"
        }
    }
}
----