Rule-Based Authorization Plugin

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.

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.

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 is being used, the "sub" JWT claim if the 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 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:

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

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

Complete Example

The example below shows how the configuration properties above can be used to achieve a typical (if simple) RBAP use-case.

{
  "authentication": {
    "class": "solr.BasicAuthPlugin", 
    "blockUnknown": true,
    "credentials": {
      "admin-user": "IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c=",
      "dev-user": "IV0EHq1OnNrj6gvRCwvFwTrZ1+z1oBbnQdiVC3otuq0= Ndd7LKvVBAaZIF0QAVi1ekCfAJXr1GGfLtRUXhgrF8c="
    }
  },
  "authorization": {
    "class": "solr.RuleBasedAuthorizationPlugin", 
    "user-role": { 
      "admin-user": "admin",
      "dev-user": "dev"
    },
    "permissions": [ 
      { "name": "dev-private-collection", "collection": "dev-private", "role": "dev"},
      { "name": "security-read", "role": "admin"},
      { "name": "security-edit", "role": "admin"}
    ]
  }
}
1Solr is using the Basic Authentication plugin for authentication. This configuration establishes two users: admin-user and dev-user.
2The authorization property begins the authorization configuration. Solr will use RBAP for authorization.
3Two roles are defined: admin and dev. Each user belongs to one role: admin-user is an admin, and dev-user is a dev.
4Three 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 ("admin") APIs. If not specified, this property defaults to "*".

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 paths this permission applies to. The value can either be a single path string, or a JSON array containing multiple strings. For APIs accessing collections, path values should start after the collection name, and often just look like the request handler (e.g., "/select"). For collection-agnostic ("admin") APIs, path values should start at the "/admin path segment. The wildcard \* can be used to indicate that this permission applies to all paths. If not specified, this property defaults to null.
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:

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

"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

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.
  • schema-edit: this permission is allowed to edit a collection’s schema using the Schema API. Note that this allows schema edit permissions for all collections. If edit permissions should only be applied to specific collections, a custom permission would need to be created.
  • schema-read: this permission is allowed to read a collection’s schema using the Schema API. Note that this allows schema read permissions for all collections. If read permissions should only be applied to specific collections, a custom permission would need to be created.
  • config-edit: this permission is allowed to edit a collection’s configuration using the Config API, the Request Parameters API, and other APIs which modify configoverlay.json. Note that this allows configuration edit permissions for all collections. If edit permissions should only be applied to specific collections, a custom permission would need to be created.
  • config-read: this permission is allowed to read a collection’s configuration using the Config API, the Request Parameters API, and other APIs which modify configoverlay.json. Note that this allows configuration read permissions for all collections. If read permissions should only be applied to specific collections, a custom permission would need to be created.
  • metrics-read: this permission allows access to Solr’s Metrics API
  • metrics-history-read: this permission allows access to Solr’s Metrics History API, which provides long-term history for a select set of key Solr metrics.
  • autoscaling-read: this permission allows users to read Solr’s autoscaling configuration. This covers all read-only autoscaling APIs, including:
    • the "READ" API (/solr/admin/autoscaling)
    • the Diagnostics API (/solr/admin/autoscaling/diagnostics)
    • the Suggestions API (/solr/admin/autoscaling/suggestions)
    • The History API (/solr/admin/autoscaling/history)
  • autoscaling-write: this permission allows users to make changes to Solr’s autoscaling configuration. This covers all operations in the autoscaling Write API, including:
    • set-cluster-preferences
    • set-cluster-policy
    • set-policy
    • remove-policy
    • set-trigger
    • remove-trigger
    • set-listener
    • remove-listener
    • set-properties
  • core-admin-edit: Core admin commands that can mutate the system state.
  • core-admin-read: Read operations on the core admin API
  • collection-admin-edit: this permission is allowed to edit a collection’s configuration using the Collections API. Note that this allows configuration edit permissions for all collections. If edit permissions should only be applied to specific collections, a custom permission would need to be created. Specifically, the following actions of the Collections API would be allowed:
    • CREATE
    • RELOAD
    • SPLITSHARD
    • CREATESHARD
    • DELETESHARD
    • CREATEALIAS
    • DELETEALIAS
    • DELETE
    • DELETEREPLICA
    • ADDREPLICA
    • CLUSTERPROP
    • MIGRATE
    • ADDROLE
    • REMOVEROLE
    • ADDREPLICAPROP
    • DELETEREPLICAPROP
    • BALANCESHARDUNIQUE
    • REBALANCELEADERS
  • collection-admin-read: this permission is allowed to read a collection’s configuration using the Collections API. Note that this allows configuration read permissions for all collections. If read permissions should only be applied to specific collections, a custom permission would need to be created. Specifically, the following actions of the Collections API would be allowed:
    • LIST
    • OVERSEERSTATUS
    • CLUSTERSTATUS
    • REQUESTSTATUS
  • update: this permission is allowed to perform any update action on any collection. This includes sending documents for indexing (using an update request handler). This applies to all collections by default (collection:"*").
  • read: this permission is allowed to perform any read action on any collection. This includes querying using search handlers (using 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.

Permission Ordering and Resolution

The permission syntax discussed above doesn’t do anything to prevent multiple permissions from overlapping and applying to the same Solr APIs. In cases where multiple permissions match an incoming request, Solr chooses the first matching permission and ignores all others - even if those other permissions would match the incoming request!

Since Solr only uses the first matching permission it finds, it’s important for administrators to understand what ordering Solr uses when processing the permission list.

The ordering Solr uses is complex. Solr tries to check first any permissions which are specific or relevant to the incoming request, only moving on to more general permissions if none of the more-specific ones match. In effect, this means that different requests may check the same permissions in very different orders.

If the incoming request is collection-agnostic (doesn’t apply to a paritcular collection), Solr checks permissions in the following order:

  1. Permissions with a collection value of null and a path value matching the request’s request handler
  2. Permissions with a collection value of null and a path value of *
  3. Permissions with a collection value of null and a path value of null

If the incoming request is to a collection, Solr checks permissions in the following order:

  1. Permissions with collection and path values matching the request specifically (not a wildcard match)
  2. Permissions with collection matching the request specifically, and a path value of *
  3. Permissions with collection matching the request specifically, and a path value of null
  4. Permissions with path matching the request specifically, and a collection value of *
  5. Permissions with both collection and path values of *.
  6. Permissions with a collection value of * and a path value of null

As an example, consider the permissions below:

{"name": "read", "role": "dev"}, 
{"name": "coll-read", "path": "/select", "role": "*"}, 
{"name": "techproducts-read", "collection": "techproducts", "role": "other", "path": "/select"}, 
{"name": "all", "role": "admin"} 

All of the permissions in this list match /select queries. But different permissions will be used depending on the collection being queried.

For a query to the techproducts collection, permission 3 will be used because it specifically targets techproducts. Only users with the other role will be authorized.

For a query to a collection called collection1 on the other hand, the most specific permission present is permission 2, so all roles are given access.

Authorization API

Authorization API Endpoint

/admin/authorization: takes a set of commands to create permissions, map permissions to roles, and map roles to users.

Manage Permissions

Three commands control managing permissions:

  • set-permission: create a new permission, overwrite an existing permission definition, or assign a pre-defined permission to a role.
  • 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.

curl --user solr:SolrRocks -H 'Content-type:application/json' -d '{
  "set-permission": {"collection": null,
                     "path":"/admin/collections",
                     "params":{"action":["LIST", "CREATE"]},
                     "before": 3,
                     "role": "admin"}
}' http://localhost:8983/solr/admin/authorization

Apply an update permission on all collections to a role called dev and read permissions to a role called guest:

curl --user solr:SolrRocks -H 'Content-type:application/json' -d '{
  "set-permission": {"name": "update", "role":"dev"},
  "set-permission": {"name": "read", "role":"guest"}
}' http://localhost:8983/solr/admin/authorization

Update or Delete Permissions

Permissions can be accessed using their index in the list. Use the /admin/authorization API to see the existing permissions and their indices.

The following example updates the 'role' attribute of permission at index 3:

curl --user solr:SolrRocks -H 'Content-type:application/json' -d '{
  "update-permission": {"index": 3,
                       "role": ["admin", "dev"]}
}' http://localhost:8983/solr/admin/authorization

The following example deletes permission at index 3:

curl --user solr:SolrRocks -H 'Content-type:application/json' -d '{
  "delete-permission": 3
}' http://localhost:8983/solr/admin/authorization

Map Roles to Users

A single command allows roles to be mapped to users:

  • set-user-role: map a user to a permission.

To remove a user’s permission, you should set the role to null. There is no command to delete a user role.

The values supplied to the command are simply a user ID and one or more roles the user should have.

For example, the following would grant a user "solr" the "admin" and "dev" roles, and remove all roles from the user ID "harry":

curl -u solr:SolrRocks -H 'Content-type:application/json' -d '{
   "set-user-role" : {"solr": ["admin","dev"],
                      "harry": null}
}' http://localhost:8983/solr/admin/authorization