Basic Authentication Plugin
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 Plugins.
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 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 (Format: base64(sha256(sha256(salt+password)) base64(salt)
) 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:
{
"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' , in the encoded format detailed above, 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.
If you set |
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.
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.
-
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.
Combining Basic Authentication with Other Schemes
When using other authentication schemes, such as the JWT Authentication Plugin, you may still want to use Basic authentication for a small set of "service account" oriented client applications.
Solr provides the MultiAuthPlugin
to support multiple authentication schemes. For example, you may want to integrate Solr with an OIDC provider for user accounts,
but also use Basic for authenticating requests coming from the Prometheus metrics exporter. The MultiAuthPlugin
uses the scheme of the Authorization
header to determine which
plugin should handle each request. The MultiAuthPlugin
is useful when running Solr on Kubernetes as you can delegate user management and authentication to an OIDC provider for end-users,
but also secure the liveness and readiness endpoints using Basic
authentication, as you would not want Kubernetes to use OIDC when testing the probe endpoints.
The following example illustrates how to configure the MultiAuthPlugin
to support the Basic
and Bearer
schemes.
{
"authentication": {
"class": "solr.MultiAuthPlugin",
"schemes": [{
"scheme": "bearer",
"blockUnknown": true,
"class": "solr.JWTAuthPlugin",
"wellKnownUrl": "https://OIDC_PROVIDER_URL/.well-known/openid-configuration",
"clientId": "solr",
"redirectUris": "http://localhost:8983/solr/",
"rolesClaim": "groups"
},{
"scheme": "basic",
"blockUnknown": true,
"class": "solr.BasicAuthPlugin",
"credentials": {
"k8s-oper": "PASSWORD SALT & HASH"
},
"forwardCredentials": false
}]
}
}
For un-authenticated AJAX requests from the Solr Admin UI (i.e. requests without an Authorization
header),
the MultiAuthPlugin
forwards the request to the first plugin listed in the schemes
list. In the example above,
users will need to authenticate to the OIDC provider to login to the Admin UI.
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:
V1 API
curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"set-user": {"tom":"TomIsCool", "harry":"HarrysSecret"}}'
V2 API
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.
V1 API
curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"delete-user": ["tom", "harry"]}'
V2 API
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
.
V1 API
curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"set-property": {"blockUnknown":false}}'
V2 API
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:
V1 API
curl --user solr:SolrRocks http://localhost:8983/solr/admin/authentication -H 'Content-type:application/json' -d '{"set-property": {"realm":"My Solr users"}}'
V2 API
curl --user solr:SolrRocks http://localhost:8983/api/cluster/security/authentication -H 'Content-type:application/json' -d '{"set-property": {"realm":"My Solr users"}}'
Edit Plugin Configuration Using the MultiAuthPlugin
When using the MultiAuthPlugin
, you need to wrap the command data with a single-keyed object that identifies the scheme
.
For instance, the set-user
command for the Basic
plugin would be:
{
"set-user": {
"basic": {"tom":"TomIsCool", "harry":"HarrysSecret"}
}
}
Set a property on the Basic
plugin when using the MultiAuthPlugin
:
{
"set-property": {
"basic": {"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:
SolrRequest req ;//create a new request object
req.setBasicAuthCredentials(userName, password);
solrClient.request(req);
Query example:
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.
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:
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 ashttpBasicAuthUser
andhttpBasicAuthPassword
, respectively.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":
SOLR_AUTH_TYPE="basic"
SOLR_AUTHENTICATION_OPTS="-Dbasicauth=solr:SolrRocks"
Alternatively, the SOLR_AUTHENTICATION_OPTS
can take a path to a file, as in:
SOLR_AUTH_TYPE="basic"
SOLR_AUTHENTICATION_OPTS="-Dsolr.httpclient.config=/path/to/solr-9.6.1/server/solr/basicAuth.conf"