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`.

 This plugin only provides user authentication.
 To control user permissions, you may need to configure an authorization plugin as 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#configuring-security-json,Configuring security.json>>.

 If running in cloud mode, you can use the `bin/solr auth` command-line utility to enable security for a new installation, see: `bin/solr auth --help` for more details.

 For Basic authentication, `security.json` must have an `authentication` block 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 Authentication API, described below.

 An example `security.json` showing `authentication` and `authorization` blocks is shown below to show how authentication and authorization 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"}],
    "user-role":{"solr":"admin"}
 }}
 ----

 There are several options defined in this example:

 <1> The first block defines the authentication plugin to be used and its parameters.
 <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.

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

 If `blockUnknown` is not defined in the `security.json` file, it will default to `true`.
 This has the effect of requiring authentication for HTTP access to Solr.
 In some cases, you may not want authentication after enabling the plugin; 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 `blockUnknown` is set to `true` or omitted entirely in order for authentication to be enforced for all requests to your system.

 [WARNING]
 ====
 If you set `blockUnknown` to `false`, then *any* request that is not explicitly protected by a permission will be accessible by anonymous users!
 Consequently, you should define a role binding for every <<rule-based-authorization-plugin.adoc#permissions,predefined>> permission you want to protect.
 You can assign the special `role: null` binding for requests that you want to allow anonymous users to access. To protect all endpoints except those with `role:null`,
 you can add a role binding for the `all` permission and place it in the last position in `security.json`.
 ====

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

 If you are using SolrCloud, you must upload `security.json` to ZooKeeper.
 An example command and more information about securing your setup can be found at <<authentication-and-authorization-plugins#in-a-solrcloud-cluster,Authentication and Authorization Plugins In a SolrCloud Cluster>>.

 === 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 permissions and user permission assignments.
 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.

 === Per-Client Credentials
 Http2SolrClient supports setting the credentials at the client level when building it.
 This will ensure all requests issued with this particular client get the Basic Authentication headers set.

 [source,java]
 ----
 Http2SolrClient client = new Http2SolrClient.Builder(solrUrl)
         .withBasicAuthCredentials(userName, password).build();
 QueryResponse rsp = req.process(client);
 ----

 CloudHttp2SolrClient supports receiving an `Http2SolrClient.Builder` instance for creating its internal client, so to set the credentials at the client level you could use a code like:

 [source,java]
 ----
 Http2SolrClient.Builder http2ClientBuilder = Http2SolrClient.Builder().withBasicAuthCredentials(userName, password);
 CloudHttp2SolrClient client = new CloudHttp2SolrClient.Builder(zkHostList, chroot)
             .withInternalClientBuilder(http2ClientBuilder).build();
 QueryResponse rsp = req.process(client);
 ----

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

 Once Basic authentication is enabled, all requests to the Solr Control Script (`bin/solr`) must contain user credentials.
 To ensure this, 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"
 ----

 Alternatively, the `SOLR_AUTHENTICATION_OPTS` can take a path to a file, as in:

 [source,bash]
 SOLR_AUTH_TYPE="basic"
 SOLR_AUTHENTICATION_OPTS="-Dsolr.httpclient.config=/path/to/solr-{solr-docs-version}.0/server/solr/basicAuth.conf"
	= 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`.

	This plugin only provides user authentication.
	To control user permissions, you may need to configure an authorization plugin as 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#configuring-security-json,Configuring security.json>>.

	If running in cloud mode, you can use the `bin/solr auth` command-line utility to enable security for a new installation, see: `bin/solr auth --help` for more details.

	For Basic authentication, `security.json` must have an `authentication` block 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 Authentication API, described below.

	An example `security.json` showing `authentication` and `authorization` blocks is shown below to show how authentication and authorization 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"}],
	"user-role":{"solr":"admin"}
	}}
	----

	There are several options defined in this example:

	<1> The first block defines the authentication plugin to be used and its parameters.
	<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.

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

	If `blockUnknown` is not defined in the `security.json` file, it will default to `true`.
	This has the effect of requiring authentication for HTTP access to Solr.
	In some cases, you may not want authentication after enabling the plugin; 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 `blockUnknown` is set to `true` or omitted entirely in order for authentication to be enforced for all requests to your system.

	[WARNING]
	====
	If you set `blockUnknown` to `false`, then any request that is not explicitly protected by a permission will be accessible by anonymous users!
	Consequently, you should define a role binding for every <<rule-based-authorization-plugin.adoc#permissions,predefined>> permission you want to protect.
	You can assign the special `role: null` binding for requests that you want to allow anonymous users to access. To protect all endpoints except those with `role:null`,
	you can add a role binding for the `all` permission and place it in the last position in `security.json`.
	====

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

	If you are using SolrCloud, you must upload `security.json` to ZooKeeper.
	An example command and more information about securing your setup can be found at <<authentication-and-authorization-plugins#in-a-solrcloud-cluster,Authentication and Authorization Plugins In a SolrCloud Cluster>>.

	=== 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 permissions and user permission assignments.
	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.

	=== Per-Client Credentials
	Http2SolrClient supports setting the credentials at the client level when building it.
	This will ensure all requests issued with this particular client get the Basic Authentication headers set.

	[source,java]
	----
	Http2SolrClient client = new Http2SolrClient.Builder(solrUrl)
	.withBasicAuthCredentials(userName, password).build();
	QueryResponse rsp = req.process(client);
	----

	CloudHttp2SolrClient supports receiving an `Http2SolrClient.Builder` instance for creating its internal client, so to set the credentials at the client level you could use a code like:

	[source,java]
	----
	Http2SolrClient.Builder http2ClientBuilder = Http2SolrClient.Builder().withBasicAuthCredentials(userName, password);
	CloudHttp2SolrClient client = new CloudHttp2SolrClient.Builder(zkHostList, chroot)
	.withInternalClientBuilder(http2ClientBuilder).build();
	QueryResponse rsp = req.process(client);
	----

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

	Once Basic authentication is enabled, all requests to the Solr Control Script (`bin/solr`) must contain user credentials.
	To ensure this, 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"
	----

	Alternatively, the `SOLR_AUTHENTICATION_OPTS` can take a path to a file, as in:

	[source,bash]
	SOLR_AUTH_TYPE="basic"
	SOLR_AUTHENTICATION_OPTS="-Dsolr.httpclient.config=/path/to/solr-{solr-docs-version}.0/server/solr/basicAuth.conf"