solr/solr-ref-guide/src/basic-authentication-plugin.adoc - solr - Git at Google

 = Basic 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.

 Solr can support Basic authentication for users with the use of the BasicAuthPlugin.

 An authorization plugin is also available to configure Solr with permissions to perform various activities in the system. The authorization plugin is described in the section <<rule-based-authorization-plugin.adoc#,Rule-Based Authorization Plugin>>.

 == Enable Basic Authentication

 To use Basic authentication, you must first create a `security.json` file. This file and where to put it is described in detail in the section <<authentication-and-authorization-plugins.adoc#enable-plugins-with-security-json,Enable Plugins with security.json>>.

 For Basic authentication, the `security.json` file must have an `authentication` part which defines the class being used for authentication. Usernames and passwords (as a sha256(password+salt) hash) could be added when the file is created, or can be added later with the Basic authentication API, described below.

 The `authorization` part is not related to Basic authentication, but is a separate authorization plugin designed to support fine-grained user access control. For more information, see the section <<rule-based-authorization-plugin.adoc#,Rule-Based Authorization Plugin>>.

 An example `security.json` showing both sections is shown below to show how these plugins can work together:

 [source,json]
 ----
 {
 "authentication":{ <1>
    "blockUnknown": true, <2>
    "class":"solr.BasicAuthPlugin",
    "credentials":{"solr":"IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="}, <3>
    "realm":"My Solr users", <4>
    "forwardCredentials": false <5>
 },
 "authorization":{
    "class":"solr.RuleBasedAuthorizationPlugin",
    "permissions":[{"name":"security-edit",
       "role":"admin"}], <6>
    "user-role":{"solr":"admin"} <7>
 }}
 ----

 There are several things defined in this file:

 <1> Basic authentication and rule-based authorization plugins are enabled.
 <2> The parameter `"blockUnknown":true` means that unauthenticated requests are not allowed to pass through.
 <3> A user called 'solr', with a password `'SolrRocks'` has been defined.
 <4> We override the `realm` property to display another text on the login prompt.
 <5> The parameter `"forwardCredentials":false` means we let Solr's PKI authenticaion handle distributed request instead of forwarding the Basic Auth header.
 <6> The 'admin' role has been defined, and it has permission to edit security settings.
 <7> The 'solr' user has been defined to the 'admin' role.

 Save your settings to a file called `security.json` locally. If you are using Solr in standalone mode, you should put this file in `$SOLR_HOME`.

 If `blockUnknown` does not appear in the `security.json` file, it will default to `false`. This has the effect of not requiring authentication at all. In some cases, you may want this; for example, if you want to have `security.json` in place but aren't ready to enable authentication. However, you will want to ensure that this parameter is set to `true` in order for authentication to be truly enabled in your system.

 If `realm` is not defined, it will default to `solr`.

 If you are using SolrCloud, you must upload `security.json` to ZooKeeper. You can use this example command, ensuring that the ZooKeeper port is correct:

 [source,bash]
 ----
 $ bin/solr zk cp file:path_to_local_security.json zk:/security.json -z localhost:9983
 ----

 NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.

 === Caveats

 There are a few things to keep in mind when using the Basic authentication plugin.

 * Credentials are sent in plain text by default. It's recommended to use SSL for communication when Basic authentication is enabled, as described in the section <<enabling-ssl.adoc#,Enabling SSL>>.
 * A user who has access to write permissions to `security.json` will be able to modify all the permissions and how users have been assigned permissions. Special care should be taken to only grant access to editing security to appropriate users.
 * Your network should, of course, be secure. Even with Basic authentication enabled, you should not unnecessarily expose Solr to the outside world.

 == Editing Basic Authentication Plugin Configuration

 An Authentication API allows modifying user IDs and passwords. The API provides an endpoint with specific commands to set user details or delete a user.

 === API Entry Point

 * v1: `\http://localhost:8983/solr/admin/authentication`
 * v2: `\http://localhost:8983/api/cluster/security/authentication`

 This endpoint is not collection-specific, so users are created for the entire Solr cluster. If users need to be restricted to a specific collection, that can be done with the authorization rules.

 === Add a User or Edit a Password

 The `set-user` command allows you to add users and change their passwords. For example, the following defines two users and their passwords:

 [.dynamic-tabs]
 --
 [example.tab-pane#v1set-user]
 ====
 [.tab-label]*V1 API*

 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"set-user": {"tom":"TomIsCool", "harry":"HarrysSecret"}}'
 ----
 ====

 [example.tab-pane#v2set-user]
 ====
 [.tab-label]*V2 API*
 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d '{"set-user": {"tom":"TomIsCool", "harry":"HarrysSecret"}}'
 ----
 ====
 --

 === Delete a User

 The `delete-user` command allows you to remove a user. The user password does not need to be sent to remove a user. In the following example, we've asked that user IDs 'tom' and 'harry' be removed from the system.

 [.dynamic-tabs]
 --
 [example.tab-pane#v1delete-user]
 ====
 [.tab-label]*V1 API*
 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d  '{"delete-user": ["tom", "harry"]}'
 ----
 ====

 [example.tab-pane#v2delete-user]
 ====
 [.tab-label]*V2 API*
 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d  '{"delete-user": ["tom", "harry"]}'
 ----
 ====
 --

 === Set a Property

 Set properties for the authentication plugin. The currently supported properties for the Basic Authentication plugin are `blockUnknown`, `realm` and `forwardCredentials`.

 [.dynamic-tabs]
 --
 [example.tab-pane#v1set-property-blockUnknown]
 ====
 [.tab-label]*V1 API*

 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d  '{"set-property": {"blockUnknown":false}}'
 ----
 ====

 [example.tab-pane#v2set-property-blockUnknown]
 ====
 [.tab-label]*V2 API*

 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d  '{"set-property": {"blockUnknown":false}}'
 ----
 ====
 --

 The authentication realm defaults to `solr` and is displayed in the `WWW-Authenticate` HTTP header and in the Admin UI login page. To change the realm, set the `realm` property:

 [.dynamic-tabs]
 --
 [example.tab-pane#v1set-property-realm]
 ====
 [.tab-label]*V1 API*

 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d  '{"set-property": {"realm":"My Solr users"}}'
 ----
 ====

 [example.tab-pane#v2set-property-realm]
 ====
 [.tab-label]*V2 API*

 [source,bash]
 ----
 curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d  '{"set-property": {"realm":"My Solr users"}}'
 ----
 ====
 --

 == Using Basic Auth with SolrJ

 There are two main ways to use SolrJ with Solr servers protected by basic authentication: either the permissions can be set on each individual request, or the underlying http client can be configured to add credentials to all requests that it sends.

 === Per-Request Basic Auth Credentials
 The simplest way to setup basic authentication in SolrJ is use the `setBasicAuthCredentials` method on each request as in this example:

 [source,java]
 ----
 SolrRequest req ;//create a new request object
 req.setBasicAuthCredentials(userName, password);
 solrClient.request(req);
 ----

 Query example:

 [source,java]
 ----
 QueryRequest req = new QueryRequest(new SolrQuery("*:*"));
 req.setBasicAuthCredentials(userName, password);
 QueryResponse rsp = req.process(solrClient);
 ----

 While this is method is simple, it can often be inconvenient to ensure the credentials are provided everywhere they're needed.  It also doesn't work with the many `SolrClient` methods which don't consume `SolrRequest` objects.

 === Global (JVM) Basic Auth Credentials
 Alternatively, users can use SolrJ's `PreemptiveBasicAuthClientBuilderFactory` to add basic authentication credentials to _all_ requests automatically.
 To enable this feature, users should set the following system property `-Dsolr.httpclient.builder.factory=org.apache.solr.client.solrj.impl.PreemptiveBasicAuthClientBuilderFactory`.
 `PreemptiveBasicAuthClientBuilderFactory` allows applications to provide credentials in two different ways:

 . The `basicauth` system property can be passed, containing the credentials directly (e.g., `-Dbasicauth=username:password`).  This option is straightforward, but may expose the credentials in the command line, depending on how they're set.
 . The `solr.httpclient.config` system property can be passed, containing a path to a properties file holding the credentials.  Inside this file the username and password can be specified as `httpBasicAuthUser` and `httpBasicAuthPassword`, respectively.
 +
 [source,bash]
 ----
 httpBasicAuthUser=my_username
 httpBasicAuthPassword=secretPassword
 ----

 == Using the Solr Control Script with Basic Auth

 Add the following line to the `solr.in.sh` or `solr.in.cmd` file. This example tells the `bin/solr` command line to to use "basic" as the type of authentication, and to pass credentials with the user-name "solr" and password "SolrRocks":

 [source,bash]
 ----
 SOLR_AUTH_TYPE="basic"
 SOLR_AUTHENTICATION_OPTS="-Dbasicauth=solr:SolrRocks"
 ----
	= Basic 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.

	Solr can support Basic authentication for users with the use of the BasicAuthPlugin.

	An authorization plugin is also available to configure Solr with permissions to perform various activities in the system. The authorization plugin is described in the section <<rule-based-authorization-plugin.adoc#,Rule-Based Authorization Plugin>>.

	== Enable Basic Authentication

	To use Basic authentication, you must first create a `security.json` file. This file and where to put it is described in detail in the section <<authentication-and-authorization-plugins.adoc#enable-plugins-with-security-json,Enable Plugins with security.json>>.

	For Basic authentication, the `security.json` file must have an `authentication` part which defines the class being used for authentication. Usernames and passwords (as a sha256(password+salt) hash) could be added when the file is created, or can be added later with the Basic authentication API, described below.

	The `authorization` part is not related to Basic authentication, but is a separate authorization plugin designed to support fine-grained user access control. For more information, see the section <<rule-based-authorization-plugin.adoc#,Rule-Based Authorization Plugin>>.

	An example `security.json` showing both sections is shown below to show how these plugins can work together:

	[source,json]
	----
	{
	"authentication":{ <1>
	"blockUnknown": true, <2>
	"class":"solr.BasicAuthPlugin",
	"credentials":{"solr":"IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="}, <3>
	"realm":"My Solr users", <4>
	"forwardCredentials": false <5>
	},
	"authorization":{
	"class":"solr.RuleBasedAuthorizationPlugin",
	"permissions":[{"name":"security-edit",
	"role":"admin"}], <6>
	"user-role":{"solr":"admin"} <7>
	}}
	----

	There are several things defined in this file:

	<1> Basic authentication and rule-based authorization plugins are enabled.
	<2> The parameter `"blockUnknown":true` means that unauthenticated requests are not allowed to pass through.
	<3> A user called 'solr', with a password `'SolrRocks'` has been defined.
	<4> We override the `realm` property to display another text on the login prompt.
	<5> The parameter `"forwardCredentials":false` means we let Solr's PKI authenticaion handle distributed request instead of forwarding the Basic Auth header.
	<6> The 'admin' role has been defined, and it has permission to edit security settings.
	<7> The 'solr' user has been defined to the 'admin' role.

	Save your settings to a file called `security.json` locally. If you are using Solr in standalone mode, you should put this file in `$SOLR_HOME`.

	If `blockUnknown` does not appear in the `security.json` file, it will default to `false`. This has the effect of not requiring authentication at all. In some cases, you may want this; for example, if you want to have `security.json` in place but aren't ready to enable authentication. However, you will want to ensure that this parameter is set to `true` in order for authentication to be truly enabled in your system.

	If `realm` is not defined, it will default to `solr`.

	If you are using SolrCloud, you must upload `security.json` to ZooKeeper. You can use this example command, ensuring that the ZooKeeper port is correct:

	[source,bash]
	----
	$ bin/solr zk cp file:path_to_local_security.json zk:/security.json -z localhost:9983
	----

	NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.

	=== Caveats

	There are a few things to keep in mind when using the Basic authentication plugin.

	* Credentials are sent in plain text by default. It's recommended to use SSL for communication when Basic authentication is enabled, as described in the section <<enabling-ssl.adoc#,Enabling SSL>>.
	* A user who has access to write permissions to `security.json` will be able to modify all the permissions and how users have been assigned permissions. Special care should be taken to only grant access to editing security to appropriate users.
	* Your network should, of course, be secure. Even with Basic authentication enabled, you should not unnecessarily expose Solr to the outside world.

	== Editing Basic Authentication Plugin Configuration

	An Authentication API allows modifying user IDs and passwords. The API provides an endpoint with specific commands to set user details or delete a user.

	=== API Entry Point

	* v1: `\http://localhost:8983/solr/admin/authentication`
	* v2: `\http://localhost:8983/api/cluster/security/authentication`

	This endpoint is not collection-specific, so users are created for the entire Solr cluster. If users need to be restricted to a specific collection, that can be done with the authorization rules.

	=== Add a User or Edit a Password

	The `set-user` command allows you to add users and change their passwords. For example, the following defines two users and their passwords:

	[.dynamic-tabs]
	--
	[example.tab-pane#v1set-user]
	====
	[.tab-label]V1 API

	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"set-user": {"tom":"TomIsCool", "harry":"HarrysSecret"}}'
	----
	====

	[example.tab-pane#v2set-user]
	====
	[.tab-label]V2 API
	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d '{"set-user": {"tom":"TomIsCool", "harry":"HarrysSecret"}}'
	----
	====
	--

	=== Delete a User

	The `delete-user` command allows you to remove a user. The user password does not need to be sent to remove a user. In the following example, we've asked that user IDs 'tom' and 'harry' be removed from the system.

	[.dynamic-tabs]
	--
	[example.tab-pane#v1delete-user]
	====
	[.tab-label]V1 API
	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"delete-user": ["tom", "harry"]}'
	----
	====

	[example.tab-pane#v2delete-user]
	====
	[.tab-label]V2 API
	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d '{"delete-user": ["tom", "harry"]}'
	----
	====
	--

	=== Set a Property

	Set properties for the authentication plugin. The currently supported properties for the Basic Authentication plugin are `blockUnknown`, `realm` and `forwardCredentials`.

	[.dynamic-tabs]
	--
	[example.tab-pane#v1set-property-blockUnknown]
	====
	[.tab-label]V1 API

	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"set-property": {"blockUnknown":false}}'
	----
	====

	[example.tab-pane#v2set-property-blockUnknown]
	====
	[.tab-label]V2 API

	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d '{"set-property": {"blockUnknown":false}}'
	----
	====
	--

	The authentication realm defaults to `solr` and is displayed in the `WWW-Authenticate` HTTP header and in the Admin UI login page. To change the realm, set the `realm` property:

	[.dynamic-tabs]
	--
	[example.tab-pane#v1set-property-realm]
	====
	[.tab-label]V1 API

	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"set-property": {"realm":"My Solr users"}}'
	----
	====

	[example.tab-pane#v2set-property-realm]
	====
	[.tab-label]V2 API

	[source,bash]
	----
	curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d '{"set-property": {"realm":"My Solr users"}}'
	----
	====
	--

	== Using Basic Auth with SolrJ

	There are two main ways to use SolrJ with Solr servers protected by basic authentication: either the permissions can be set on each individual request, or the underlying http client can be configured to add credentials to all requests that it sends.

	=== Per-Request Basic Auth Credentials
	The simplest way to setup basic authentication in SolrJ is use the `setBasicAuthCredentials` method on each request as in this example:

	[source,java]
	----
	SolrRequest req ;//create a new request object
	req.setBasicAuthCredentials(userName, password);
	solrClient.request(req);
	----

	Query example:

	[source,java]
	----
	QueryRequest req = new QueryRequest(new SolrQuery(":"));
	req.setBasicAuthCredentials(userName, password);
	QueryResponse rsp = req.process(solrClient);
	----

	While this is method is simple, it can often be inconvenient to ensure the credentials are provided everywhere they're needed. It also doesn't work with the many `SolrClient` methods which don't consume `SolrRequest` objects.

	=== Global (JVM) Basic Auth Credentials
	Alternatively, users can use SolrJ's `PreemptiveBasicAuthClientBuilderFactory` to add basic authentication credentials to _all_ requests automatically.
	To enable this feature, users should set the following system property `-Dsolr.httpclient.builder.factory=org.apache.solr.client.solrj.impl.PreemptiveBasicAuthClientBuilderFactory`.
	`PreemptiveBasicAuthClientBuilderFactory` allows applications to provide credentials in two different ways:

	. The `basicauth` system property can be passed, containing the credentials directly (e.g., `-Dbasicauth=username:password`). This option is straightforward, but may expose the credentials in the command line, depending on how they're set.
	. The `solr.httpclient.config` system property can be passed, containing a path to a properties file holding the credentials. Inside this file the username and password can be specified as `httpBasicAuthUser` and `httpBasicAuthPassword`, respectively.
	+
	[source,bash]
	----
	httpBasicAuthUser=my_username
	httpBasicAuthPassword=secretPassword
	----

	== Using the Solr Control Script with Basic Auth

	Add the following line to the `solr.in.sh` or `solr.in.cmd` file. This example tells the `bin/solr` command line to to use "basic" as the type of authentication, and to pass credentials with the user-name "solr" and password "SolrRocks":

	[source,bash]
	----
	SOLR_AUTH_TYPE="basic"
	SOLR_AUTHENTICATION_OPTS="-Dbasicauth=solr:SolrRocks"
	----