Apache Solr Documentation

6.5 Ref Guide (PDF Download)
Solr Tutorial
Solr Community Wiki

Older Versions of this Guide (PDF)

6.6 Draft Ref Guide Topics


This Unreleased Guide Covers Apache Solr 6.6
As of 5 May 2017, committer editing of this Ref Guide is LOCKED for migration to the new Ref Guide. See SOLR-10290 for details.

Skip to end of metadata
Go to start of metadata

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.

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

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

There are several things defined in this file:

  • Basic authentication and rule-based authorization plugins are enabled.
  • A user called 'solr', with a password 'SolrRocks' has been defined.
  • The parameter "blockUnknown": true means that unauthenticated requests are not allowed to pass through.
  • The 'admin' role has been defined, and it has permission to edit security settings.
  • 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 you are using SolrCloud, you must upload security.json to ZooKeeper. You can use this example command, ensuring that the ZooKeeper port is correct:


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


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:

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.

Set a property

Set arbitrary properties for authentication plugin. The only supported property is 'blockUnknown'

Using BasicAuth with SolrJ

In SolrJ, the basic authentication credentials need to be set for each request as in this example:

Query example:

Using Command Line scripts with BasicAuth

Add the following line to the solr.in.sh/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":



  • No labels


  1. The authenticationProvider is hard coded to Sha256AuthenticationProvider. I'm thinking if it would not be possible to add a new LDAPAuthenticationProvider, but then BasicAuthPlugin needs to parse the pluginConfig map, and look for e.g. "authenticationProvider""some.Provider", was this the original intention behind the design?

    1. Yes. The objective of the design was to plug in alternate authentication providers.please open a ticket if you wish to add the functionality 

      1. Filed  SOLR-8951 - Allow pluggable Authentication Providers in BasicAuthPlugin Open  for pluggable providers.

  2. Hi, I encountered some problems with solr-5.3.1. After I initialized the solrcloud and set up BasicAuthPlugin and RuleBasedAuthorizationPlugin, something wrong happened to my solrcloud. I can't Synchronization as usual. The server log as follows:
    master log
    Invalid key PKIAuthenticationPlugin
    silver log
    Error while trying to recover:org.apache.solr.client.solrj.impl.HttpSolrClient$RemoteSolrException: Error from server at Expected MIME type application/octet-stream but got text/html. <html> RecoveryStrategy

    What can I do next?


    1. Hi, I encountered the same issue.

      Have you found a solution?

      Thank you!

  3. It took me quite a while to figure out how to configure stand-alone solr to authenticate user, so I'd like to dump here the knowledge, since this page is one of the first in google results.

    Say we have solr-5.5.1 running on the Ubuntu (Ubuntu 16.04.1 LTS) machine. Solr instance is configured as a service according to Taking Solr to Production.

    1. Find out jetty.home variable value:
      1.  Search for for jetty files:

        sudo find / -name "jetty-util-*.jar"

      2. Use the found path from previous command and type the following
        java -jar /opt/solr-5.5.1/server/start.jar --list-config
        output (shortened):

        Java Environment:
        java.home = /usr/lib/jvm/java-8-openjdk-amd64/jre
        Jetty Environment:
        jetty.version = 9.2.13.v20150730
        jetty.home = /opt/solr-5.5.1/server

    2. Add the following block inside /opt/solr/server/etc/jetty.xml:
        <Call name="addBean">
            <New class="org.eclipse.jetty.security.HashLoginService">
              <Set name="name">Solr Admin Access</Set>
              <Set name="config"><SystemProperty name="jetty.home" default="."/>/etc/realm.properties</Set>
              <Set name="refreshInterval">0</Set>

    3. Add the following two blocks Inside /opt/solr/server/solr-webapp/webapp/WEB-INF/web.xml (adjust path to match jetty home above):


            <web-resource-name>Solr authenticated application</web-resource-name>

          <realm-name>Solr Admin Access</realm-name>

    4. To generate the password use the path found in pt.1 and issue the password generator command:
      java -cp /opt/solr-5.5.1/server/lib/jetty-util-9.2.13.v20150730.jar org.eclipse.jetty.util.security.Password <username> <hash>
      sample output for admin user:
        2016-08-30 12:30:41.080:INFO::main: Logging initialized @109ms

      we will need the OBF:<hash> from that output.
    5. Create the new /opt/solr-5.5.1/server/etc/realm.properties (adjust path to match jetty home above):
      solr: OBF:valid-password-hash-here-see-example-above, admin
      <username>: <password>, <role>

    Hope this will save somebody time.

    Used materials:
    1. this page
    2. http://stackoverflow.com/questions/28043957/how-to-set-apache-solr-admin-password
    3. http://stackoverflow.com/questions/33750045/how-can-i-secure-solr-5-3-1-only-admin-pages?noredirect=1&lq=1
    4. http://stackoverflow.com/questions/28314875/jetty-solr-admin-panel-password
    5. https://wiki.apache.org/solr/SolrSecurity 
    1. I don't think this documentation belongs to this page. This enables basic auth in jetty. it has nothing to do with the BasicAuthPlugin

      1. Well, you are right. Strictly speaking this has very little to do with BasicAuthPlugin. But as I mentioned in the doc, search in google for "protecting solr with http auth" will lead here. I'm happy to extract this doc out of here and put it into more relevant place, but I still think it is a good idea to leave here a use-case description and link to the doc which will describe why and how to configure jetty for HTTP auth.

        1. See  SOLR-9481  which will allow Basic Auth to be used in standalone mode without messing with Jetty

    2. Great... Anton Boritskiy

      Can you please help me to add multpile security-constraint and roles.


  4. This page doesn't describe the basic auth capabilities for Streaming expressions. Is basic auth not supported for Streaming expressions?

    1. Streaming expressions are really just a request syntax to a Solr request handler, so however you are making other requests (such as with SolrJ or with HTTP requests) should work for those as well.

  5. Hi Team,


     I am trying for Solr Authentication by taking a reference from Below code. Will you please elaborate more on this.

    Using BasicAuth with SolrJ

    In SolrJ the basic authentication credentials need to be set for each request as in this example:


    SolrRequest req ;//create a new request object 
    req.setBasicAuthCredentials(userName, password); 

    How to create SolrRequest object?


  6. Hello,

    I need help is securing Solr running in Standalone mode. I am running Solr in Localhost. I added the security.json into $SOLR_HOME and run the solr using ../bin/solr start command and when I opened the Solr Admin Panel using http://localhost:8983/solr/ , it didn't ask me for username and password in order to login. Am doing anything wrong? 

    I am using Solr v6.1.0

    1. The UI is just static files and are not protected, by design. Try performing a search or something from the UI and you should be prompted for password.

      1. Hey Jan Høydahl, thanks for your reply. 

        My issue is resolved by using new Solr version which is "Solr v6.5".