| = 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. |
| |
| 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. |
| |
| 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. |
| |
| [WARNING] |
| ==== |
| If you set `blockUnknown` to `false`, then *any* request that is not explicitly protected by a permission will be accessible to 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-solrcloud-mode,Authentication and Authorization Plugins In SolrCloud Mode>>. |
| |
| === 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. |
| |
| == Combining Basic Authentication with Other Schemes |
| :experimental: |
| |
| When using other authentication schemes, such as the <<jwt-authentication-plugin.adoc#,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. |
| |
| [source,json] |
| ---- |
| { |
| "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: |
| |
| [.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"}}' |
| ---- |
| ==== |
| -- |
| |
| === 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: |
| |
| [source,json] |
| ---- |
| { |
| "set-user": { |
| "basic": {"tom":"TomIsCool", "harry":"HarrysSecret"} |
| } |
| } |
| ---- |
| |
| Set a property on the `Basic` plugin when using the `MultiAuthPlugin`: |
| [source,json] |
| ---- |
| { |
| "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: |
| |
| [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 |
| |
| 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" |
| ---- |