solr/solr-ref-guide/src/security-ui.adoc

= Security UI
:experimental:
// 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.

The Security screen allows administrators with the `security-edit` permission to manage users, roles, and permissions.
The Security screen works with Solr running in cloud and standalone modes.

.Security Screen
image::images/security-ui/security.png[]

== Getting Started

The Security screen warns you if security is not enabled for Solr. You are strongly encouraged to enable security for Solr instances exposed on any network other than localhost.

image::images/security-ui/security-not-enabled-warn.png[image,width=500]

When first getting started with Solr, use the `bin/solr auth` command-line utility to enable security for your Solr installation (cloud mode only), see <<solr-control-script-reference.adoc#authentication,bin/solr auth>> for usage instructions.
For example, the following command will enable *basic authentication* and prompt you for the username and password for the initial user with administrative access:
[source,bash]
----
 bin/solr auth enable -type basicAuth -prompt true -z localhost:2181 -blockUnknown true
----
_Note: The `auth` utility only works with Solr running in cloud mode and thus requires a Zookeeper connection string passed via the `-z` option._

After enabling security, you'll need to refresh the Admin UI and login with the credentials you provided to the `auth` utility to see the updated Security panel.
You do not need to restart Solr as the security configuration will be refreshed from Zookeeper automatically.

The Security screen provides the following features:

* Security Settings: Details about the configured authentication and authorization plugins.
* Users: Read, create, update, and delete user accounts if using the <<basic-authentication-plugin.adoc#,Basic Authentication>> plugin; this panel is disabled for all other authentication plugins.
* Roles: Read, create, and update roles if using the <<rule-based-authorization-plugin.adoc#,Rule-based Authorization>> plugin; this panel is disabled for all other authorization plugins.
* Permissions: Read, create, update, and delete permissions if using the <<rule-based-authorization-plugin.adoc#,Rule-based Authorization>> plugin.

== User Management

Administrators can read, create, update, and delete user accounts when using the <<basic-authentication-plugin.adoc#,Basic Authentication>> plugin.

image::images/security-ui/users.png[image,width=500]

.Limited User Management Capabilities
[NOTE]
====
Solr's user management is intended to be used by administrators to grant access to protected APIs and lacks common user account management facilities, like password expiration and password self-service (change / reset / recovery).
Consequently, if a user account has been compromised, then an administrator needs to change the password or disable that account using the UI or API.
====

To edit a user account, click on the row in the table to open the edit user dialog. You can change a user's password and change their role membership.

image::images/security-ui/edit-user-dialog.png[image,width=400]

For systems with many user accounts, use the filter controls at the top of the user table to find users based on common properties.

image::images/security-ui/filter-users.png[image,width=400]

For other authentication plugins, such as the <<jwt-authentication-plugin.adoc#,JWT Authentication>> plugin, this panel will be disabled as users are managed by an external system.

== Role Management

<<rule-based-authorization-plugin.adoc#roles,Roles>> link users to permissions. If using the <<rule-based-authorization-plugin.adoc#,Rule-based Authorization>> plugin, administrators can read, create, and update roles. Deleting roles is not supported.

image::images/security-ui/roles.png[image,width=500]

To edit a role, simply click on the corresponding row in the table.

If not using the Rule-based Authorization plugin, the Roles panel will be disabled as user role assignment is managed by an external system.

== Permission Management

The *Permissions* panel on the Security screen allows administrators to read, create, update, and delete permissions.

image::images/security-ui/permissions.png[image,width=900]

For detailed information about how permissions work in Solr, see: <<rule-based-authorization-plugin.adoc#permissions,Rule-based Authorization Permissions>>.

=== Add Permission

Click on the btn:[Add Permission] button to open the Add Permission dialog.

image::images/security-ui/add-permission.png[image,width=600]

You can _either_ select a *Predefined* permission from the drop-down select list or provide a unique name for a custom permission.
Creating a new *Predefined* permission is simply a matter of mapping the permission to zero or more roles as the other settings, such as path, are immutable for predefined permissions.
If you need fine-grained control over the path, request method, or collection, then create a custom permission.

If you do not select any roles for a permission, then the permission is assigned the `null` role, which means grants the permission to anonymous users.
However, if *Block anonymous requests* (`blockUnknown=true`) is checked, then anonymous users will not be allowed to make requests, thus permission with the `null` role are effectively inactive.

To edit a permission, simply click on the corresponding row in the table. When editing a permission, the current index of the permission in the list of permissions is editable.
This allows you to re-order permissions if needed; see <<rule-based-authorization-plugin.adoc#permission-ordering-and-resolution,Permission Ordering>>.
In general, you want to permissions listed from most specific to least specific in `security.json`.