anchor.diff:  // specific language governing permissions and limitations
   // under the License.
   
  -Solr allows configuring roles to control user access to the system.
  -
  -This is accomplished through rule-based permission definitions which are assigned to users. The roles are fully customizable, and provide the ability to limit access to specific collections, request handlers, request parameters, and request methods.
  -
  -The roles can be used with any of the authentication plugins or with a custom authentication plugin if you have created one. You will only need to ensure that you configure the role-to-user mappings with the proper user IDs that your authentication system provides.
  -
  -Once defined through the API, roles are stored in `security.json`.
  +Solr's authentication plugins control whether users can access Solr in a binary fashion.  A user is either authenticated, or they aren't.  For more fine-grained access control, Solr's Rule-Based Authorization Plugin (hereafter, "RBAP") can be used.
   
   [CAUTION]
   ====
   Solr's Admin UI interacts with Solr using its regular APIs. When rule-based authorization is in use, logged-in users not authorized to access the full range of these APIs may see some sections of the UI that appear blank or "broken". For best results, the Admin UI should only be accessed by users with full API access.
   ====
   
  -== Enable the Authorization Plugin
  -
  -The plugin must be enabled in `security.json`. This file and where to put it in your system is described in detail in the section <<authentication-and-authorization-plugins.adoc#enable-plugins-with-security-json,Enable Plugins with security.json>>.
  -
  -This file has two parts, the `authentication` part and the `authorization` part. The `authentication` part stores information about the class being used for authentication.
  -
  -The `authorization` part is not related to Basic authentication, but is a separate authorization plugin designed to support fine-grained user access control. When creating `security.json` you can add the permissions to the file, or you can use the Authorization API described below to add them as needed.
  -
  -This example `security.json` shows how the <<basic-authentication-plugin.adoc#basic-authentication-plugin,Basic authentication plugin>> can work with this authorization plugin:
  +== Rule-Based Auth Concepts
  +
  +"Users", "roles" and "permissions" play a central role in configuring authorization correctly.
  +
  +In Rule-Based Authorization, administrators define a series of roles based on the permissions they want those roles to confer.  Users are then assigned one or more roles.
  +
  +=== Users
  +
  +The users that RBAP sees come from whatever authentication plugin has been configured.  RBAP is compatible with all of the authentication plugins that Solr ships with out of the box.  It is also compatible with any custom authentication plugins users might write, provided that the plugin sets a user principal on the HttpServletRequest it receives.  The user value seen by RBAP in each case depends on the authentication plugin being used: the Kerberos principal if the <<kerberos-authentication-plugin.adoc#kerberos-authentication-plugin,Kerberos Authentication Plugin>> is being used, the "sub" JWT claim if the <<jwt-authentication-plugin.adoc#jwt-authentication-plugin,JWT Authentication Plugin>> is being used, etc.
  +
  +=== Roles
  +
  +Roles help bridge the gap between users and permissions. Users are assigned one or more roles, and permissions are then given to each of these roles in `security.json`
  +
  +=== Permissions
  +
  +Permissions control which roles (and consequently, which users) have access to particular chunks of Solr's API.  Each permission has two main components: a description of the APIs this permission applies to, and a list of the roles that should be allowed to access to this set of APIs.
  +
  +Administrators can use permissions from a list of predefined options or define their own custom permissions, are are free to mix and match both.
  +
  +== Configuring the Rule-Based Authorization Plugin
  +
  +Like all of Solr's security plugins, configuration for RBAP lives in a file or ZooKeeper node with the name `security.json`.  See <<authentication-and-authorization-plugins.adoc#enable-plugins-with-security-json,here>> for more information on how to setup `security.json` in your cluster.
  +
  +Solr offers an <<Authorization API>> for making changes to RBAP configuration.  Authorized administrators should use this to make changes under most circumstances.  Users may also make edits to `security.json` directly if it is stored in ZooKeeper, but this is an expert-level feature and is discouraged in most circumstances.  The API simplifies some aspects of configuration, and provides error feedback that isn't provided when editing ZooKeeper directly.
  +
  +=== Configuration Syntax
  +
  +RBAP configuration consists of a small number of required configuration properties.  Each of these lives under the `authorization` top level property in `security.json`
  +
  +class:: The authorization plugin to use.  For RBAP, this value will always be `solr.RuleBasedAuthorizationPlugin`
  +user-role:: A mapping of individual users to the roles they belong to.  The value of this property is a JSON map, where each property name is a user, and each property value is either the name of a single role or a JSON array of multiple roles that the specified user belongs to.  For example:
  ++
  +[source,json]
  +----
  +"user-role": {
  +  "user1": "role1",
  +  "user2": ["role1", "role2"]
  +}
  +----
  +permissions:: A JSON array of permission rules used to restrict access to sections of Solr's API.  For example:
  ++
  +[source,json]
  +----
  +"permissions": [
  +  { "name": "read", "collection": "techproducts", "role": ["admin", "dev"] },
  +  { "name": "all", "role": "admin"}
  +]
  +----
  ++
  +The syntax for individual permissions is more involved and is treated in greater detail <<Permissions,below>>.
  +
  +=== Complete Example
  +
  +The example below shows how the configuration properties above can be used to achieve a typical (if simple) RBAP use-case.
   
   [source,json]
   ----
   {
  -"authentication":{
  -   "class":"solr.BasicAuthPlugin", <1>
  -   "blockUnknown": true, <2>
  -   "credentials":{"solr":"IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="} <3>
  -},
  -"authorization":{
  -   "class":"solr.RuleBasedAuthorizationPlugin", <4>
  -   "permissions":[{"name":"security-edit",
  -      "role":"admin"}], <5>
  -   "user-role":{"solr":"admin"} <6>
  -}}
  -----
  -
  -There are several things defined in this example:
  -
  -<1> Basic authentication plugin is enabled.
  -<2> All requests w/o credentials will be rejected with a 401 error. Set `'blockUnknown'` to false (or remove it altogether) if you wish to let unauthenticated requests to go through. However, if a particular resource is protected by a rule, they are rejected anyway with a 401 error.
  -<3> A user named 'solr', with a password has been defined.
  -<4> Rule-based authorization plugin is enabled.
  -<5> The 'admin' role has been defined, and it has permission to edit security settings.
  -<6> The 'solr' user has been defined to the 'admin' role.
  -
  -== Permission Attributes
  -
  -Each role is comprised of one or more permissions which define what the user is allowed to do. Each permission is made up of several attributes that define the allowed activity. There are some pre-defined permissions which cannot be modified.
  -
  -The permissions are consulted in order they appear in `security.json`. The first permission that matches is applied for each user, so the strictest permissions should be at the top of the list. Permissions order can be controlled with a parameter of the Authorization API, as described below.
  +  "authentication": {
  +    "class": "solr.BasicAuthPlugin", <1>
  +    "blockUnknown": true,
  +    "credentials": {
  +      "admin-user": "IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c=",
  +      "dev-user": "IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="
  +    }
  +  },
  +  "authorization": {
  +    "class": "solr.RuleBasedAuthorizationPlugin", <2>
  +    "user-role": { <3>
  +      "admin-user": "admin",
  +      "dev-user": "dev"
  +    },
  +    "permissions": [ <4>
  +      { "name": "dev-private-collection", "collection": "dev-private", "role": "dev"},
  +      { "name": "security-read", "role": "admin"},
  +      { "name": "security-edit", "role": "admin"}
  +    ]
  +  }
  +}
  +----
  +
  +<1> Solr is using the Basic Authentication plugin for authentication.  This configuration establishes two users: `admin-user` and `dev-user`.
  +<2> The `authorization` property begins the authorization configuration.  Solr will use RBAP for authorization.
  +<3> Two roles are defined: `admin` and `dev`.  Each user belongs to one role: `admin-user` is an `admin`, and `dev-user` is a `dev`.
  +<4> Three permissions restrict access to Solr.  The first permission (a "custom" permission) indicates that only the `dev` role can read from a special collection with the name `dev-private`.  The last two permissions ("predefined" permissions) indicate that only the `admin` role is permitted to use Solr's security APIs.  See below for more information on permission syntax.
  +
  +Altogether, this example carves out two restricted areas.  Only `admin-user` can access Solr's Authentication and Authorization APIs, and only `dev-user` can access their `dev-private` collection.  All other APIs are left open, and can be accessed by both users.
  +
  +== Permissions
  +
  +Solr's Rule-Based Authorization plugin supports a flexible and powerful permission syntax.  RBAP supports two types of permissions, each with a slightly different syntax.
  +
  +=== Custom Permissions
  +
  +Administrators can write their own custom permissions that can match requests based on the collection, request handler, HTTP method, particular request parameters, etc.
  +
  +Each custom permission is a JSON object under the `permissions` property, with one or more of the properties below:
  +
  +name:: An optional identifier for the permission.  For custom permissions, this is used only as a clue to administrators about what this permission does.  Even so, care must be taken when setting this property to avoid colliding with one of Solr's predefined permissions, whose names are semantically meaningful.  If this name matches a predefined permission, Solr ignores any other properties set and uses the semantics of the predefined permission instead.
  +collection:: An optional property identifying which collection(s) this permission applies to.  The value can either be a single collection name, or a JSON array containing multiple collections.  The wildcard `\*` can be used to indicate that this rule applies to all collections.  Similarly the special value "null" can be used to indicate that this permission governs Solr's collection-agnostic APIs.  If not specified, this property defaults to `["*", "null"]`.
  ++
  +[NOTE]
  +====
  +The collection property can only be used to match _collections_.  It currently cannot be used to match aliases.  Aliases are resolved before Solr's security plugins are invoked; a `collection` property given an alias will never match because RBAP will be comparing an alias name to already-resolved collection names.  Instead, set a `collection` property that contains all collections in the alias concerned (or the `*` wildcard).
  +====
  +path:: An optional property identifying which request handlers this permission applies to.  The value can either be a single request handler, or a JSON list containing multiple.  The wildcard `\*` can be used to indicate that this permission applies to all request handlers.  If not specified, this property defaults to `*`.
  +method:: An optional property identifying which HTTP methods this permission applies to.  Options include `HEAD`, `POST`, `PUT`, `GET`, `DELETE`, and the wildcard `\*`.  Multiple values can also be specified using a JSON array.  If not specified, this property defaults to `*`.
  +params:: An optional property identifying which query parameters this permission applies to.  The value is a JSON object containing the names and values of request parameters that must be matched for this permission to apply.
  ++
  +For example, this property could be used to limit the actions a role is allowed to perform with the Collections API. If the role should only be allowed to perform the LIST or CLUSTERSTATUS requests, you would define this as follows:
  ++
  +[source,json]
  +----
  +"params": {
  +   "action": ["LIST", "CLUSTERSTATUS"]
  +}
  +----
  ++
  +The request parameter value can be a simple string or a regular expression. Use the prefix `REGEX:` to use a regular expression match instead of simpler string matching
  ++
  +If the commands LIST and CLUSTERSTATUS are case insensitive, the example above can be written as follows:
  ++
  +[source,json]
  +----
  +"params": {
  +   "action": ["REGEX:(?i)LIST", "REGEX:(?i)CLUSTERSTATUS"]
  +}
  +----
  ++
  +If not specified, the permission is independent of any parameters.
  +role:: A required property identifying which role (or roles) are allowed access to the APIs controlled by this permission.  Multiple values can be specified using a JSON array.  The wildcard `*` can be used to indicate that all roles can access the described functionality.
  +
   
   === Predefined Permissions
   
  -There are several permissions that are pre-defined. These have fixed default values, which cannot be modified, and new attributes cannot be added. To use these attributes, simply define a role that includes this permission, and then assign a user to that role.
  -
  -The pre-defined permissions are:
  +Custom permissions give administrators flexibility in configuring fine-grained access control.  But in an effort to make configuration as simple as possible, RBAP also offers a handful of predefined permissions, which cover many common use-cases.
  +
  +Administrators invoke a predefined permission by choosing a `name` property that matches one of Solr's predefined permission options (listed below).  Solr has its own definition for each of these permissions, and uses this information when checking whether a predefined permission matches an incoming request.  This trades flexibility for simplicity: predefined permissions do not support the `path`, `params`, or `method` properties which custom permissions allow.
  +
  +The predefined permission names (and their effects) are:
   
   * *security-edit:* this permission is allowed to edit the security configuration, meaning any update action that modifies `security.json` through the APIs will be allowed.
   * *security-read*: this permission is allowed to read the security configuration, meaning any action that reads `security.json` settings through the APIs will be allowed.
  
positive.code: * *read*: this permission is allowed to perform any read action on any collection. This includes querying using search handlers (using <<requesthandlers-and-searchcomponents-in-solrconfig.adoc#searchhandlers,request handlers>>) such as `/select`, `/get`, `/browse`, `/tvrh`, `/terms`, `/clustering`, `/elevate`, `/export`, `/spell`, `/clustering`, and `/sql`. This applies to all collections by default ( `collection:"*"` ).
  * *all*: Any requests coming to Solr.
  
  == Authorization API
  
  === Authorization API Endpoint
  
negative.code: * `update-permission`: update some attributes of an existing permission definition.
  * `delete-permission`: remove a permission definition.
  
  Created properties can either be custom or predefined.  In addition to the permission syntax discussed above, these commands also allow permissions to have a `before` property, whose value matches the index of the permission that this new permission should be placed before in `security.json`.
  
  The following creates a new permission named "collection-mgr" that is allowed to create and list collections. The permission will be placed before the "read" permission. Note also that we have defined "collection as `null`, this is because requests to the Collections API are never collection-specific.
  
  