[lucene-solr] branch branch_8x updated: Improve docs on using basic-auth in SolrJ

[ge...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

gerlowskija pushed a commit to branch branch_8x
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git


The following commit(s) were added to refs/heads/branch_8x by this push:
     new 09b41ce  Improve docs on using basic-auth in SolrJ
09b41ce is described below

commit 09b41ce578c48d8c739ddd257ea182485dfb6ce9
Author: Jason Gerlowski <ge...@apache.org>
AuthorDate: Fri Mar 29 22:37:22 2019 -0400

    Improve docs on using basic-auth in SolrJ
---
 .../src/basic-authentication-plugin.adoc            | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/solr/solr-ref-guide/src/basic-authentication-plugin.adoc b/solr/solr-ref-guide/src/basic-authentication-plugin.adoc
index e3cd24f..a47f319 100644
--- a/solr/solr-ref-guide/src/basic-authentication-plugin.adoc
+++ b/solr/solr-ref-guide/src/basic-authentication-plugin.adoc
@@ -197,7 +197,10 @@ curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentica
 
 == Using Basic Auth with SolrJ
 
-In SolrJ, the basic authentication credentials need to be set for each request as in this example:
+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]
 ----
@@ -215,6 +218,22 @@ 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":