Rule-Based Authorization Plugins

Solr provides authorization plugins that offer fine-grained user access control to critical Solr APIs and features.

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 Plugins (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 bridge the gap between users and permissions. 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 logged-in users are mapped to the roles defined by the plugin.

There are two implementations of the plugin, which only differ in how the user’s roles are obtained:

  • RuleBasedAuthorizationPlugin: The role-to-user mappings must be defined explicitly in security.json for every possible authenticated user.

  • ExternalRoleRuleBasedAuthorizationPlugin: The role-to-user mappings are managed externally. This plugin expects the AuthenticationPlugin to provide a Principal that has the roles information as well, implementing the VerifiedUserRoles interface.

Permissions

Permissions control which roles (and consequently which users) have access to which Solr APIs.

Each permission has two main components: a description of the APIs the 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 Plugins

Like all of Solr’s security plugins, configuration for RBAP lives in a file or ZooKeeper node with the name security.json. See Configuring security.json 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

Required

Default: none

The authorization plugin to use. There are three options: solr.RuleBasedAuthorizationPlugin, solr.ExternalRoleRuleBasedAuthorizationPlugin, or solr.MultiAuthRuleBasedAuthorizationPlugin.

permissions

Optional

Default: none

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.

User roles may come from the request itself when you use the ExternalRoleRuleBasedAuthorizationPlugin for the class. In this case, skip defining permissions.

If you need to hardcode user-role mappings, then define the RuleBasedAuthorizationPlugin for the class and define the user-role mappings in security.json like this:

user-role

Optional

Default: none

A mapping of individual users to their assigned roles. The value of this parameter 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"]
  }
}
useShortName

Optional

Default: false

Determines if user-role mappings will resolve using the full principal or a shortened name provided by the authentication plugin. For example, the KerberosAuthPlugin may provide a full principal as user@EXAMPLE.COM, while the corresponding short name would be user.

For some plugins the principal name and short name may be the same.

Example for RuleBasedAuthorizationPlugin and BasicAuth

This example security.json shows how the Basic Authentication Plugin can work with the RuleBasedAuthorizationPlugin plugin:

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

Example for External Role RuleBasedAuthorizationPlugin with JWT auth

This example security.json shows how the JWT Authentication Plugin, which pulls user and user roles from JWT claims, can work with the ExternalRoleRuleBasedAuthorizationPlugin plugin:

{
"authentication":{
   "class": "solr.JWTAuthPlugin", (1)
   "jwksUrl": "https://my.key.server/jwk.json", (2)
   "rolesClaim": "roles" (3)
},
"authorization":{
   "class":"solr.ExternalRoleRuleBasedAuthorizationPlugin", (4)
   "permissions":[{"name":"security-edit",
      "role":"admin"}] (5)
}}

Let’s walk through this example:

1 JWT Authentication plugin is enabled.
2 Public keys will be pulled over HTTPS.
3 We expect each JWT token to contain a "roles" claim, which will be passed on to Authorization.
4 External Role Rule-based authorization plugin is enabled.
5 The 'admin' role has been defined, and it has permission to edit security settings.

Only requests from users having a JWT token with role "admin" will be granted the security-edit permission.

Multiple Authorization Plugins

If your security.json config uses the MultiAuthPlugin, you want to use the MultiAuthRuleBasedAuthorizationPlugin to use a different authorization plugin for each authentication plugin.

The following example illustrates using the MultiAuthRuleBasedAuthorizationPlugin to configure an authorization plugin for the Basic and Bearer schemes:

{
  "authorization": {
    "class": "solr.MultiAuthRuleBasedAuthorizationPlugin",
    "schemes": [
      {
        "scheme": "basic",
        "class": "solr.RuleBasedAuthorizationPlugin",
        "user-role": {
          "k8s-oper": ["k8s"]
        }
      },
      {
        "scheme": "bearer",
        "class": "solr.ExternalRoleRuleBasedAuthorizationPlugin"
      }
    ],
    "permissions": []
  }
}

It would be uncommon for the same user account to exist in both plugins. However, the MultiAuthRuleBasedAuthorizationPlugin combines the roles from all plugins together when determining the roles for a user.

Users should take special care to lock down the exact set of endpoints that service accounts need access to when using Basic authentication. For example, if the MultiAuthPlugin allows a k8s-oper user to use Basic authentication (while all other users go through OIDC), then the permissions configured for the k8s-oper user should only allow access to specific endpoints, such as /admin/info/system.

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 parameter, with one or more of the properties below:

name

Optional

Default: none

An identifier for the permission.

For custom permissions, this is used only as a clue to administrators about what this permission does.

Care must be taken when setting this parameter to avoid colliding with one of Solr’s predefined permissions, whose names are reserved. If this name matches a predefined permission, Solr ignores any other properties set and uses the semantics of the predefined permission instead.

collection

Optional

Default: * (all)

Defines the collection(s) the permission applies to. The value can either be a single collection name, or a JSON array containing multiple collections.

The wildcard * is 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.

The collection parameter can only contain values that are real collection names. It currently cannot be used to match aliases.

+ Aliases are resolved before Solr’s security plugins are invoked. A collection parameter given an alias as a value will never match because RBAP will be comparing an alias name to already-resolved collection names.

+ Instead, set a collection parameter that contains all collections in the alias concerned (or the * wildcard).
path

Optional

Default: null

Defines the paths the permission applies to. The value can either be a single path string, or a JSON array containing multiple strings.

For APIs that access collections, path values should start after the collection name, and often just look like the request handler (e.g., "/select").

For collection-agnostic (aka, "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.

method

Optional

Default: *

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

params

Optional

Default: none

Defines the query parameters the 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 parameter 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"]
 }
}
role

Required

Default: none

Defines 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 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. Because configs can add libraries/custom code from various locations, loading any new code via a trusted SolrConfig is explicitly allowed for users with this permission. 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, Configsets API, the Admin UI’s Files Screen, and other APIs accessing configuration. 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, some implicit admin handlers such as solr/<collection>/admin/mbeans and solr/<collection>/admin/segments, as well as other admin APIs exposing metrics.

  • health: this permission allows access to Solr’s Health Check and Ping endpoints, typically used to monitor whether a node or core is healthy.

  • 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, /tvrh, /terms, /clustering, /elevate, /export, /spell, /clustering, and /sql. This applies to all collections by default ( collection:"*" ).

  • zk-read : Permission to read content from ZK (/api/cluster/zk/data/ , /api/cluster/zk/ls/ )

  • 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 particular 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"}, (1)
{"name": "coll-read", "path": "/select", "role": "*"}, (2)
{"name": "techproducts-read", "collection": "techproducts", "role": "other", "path": "/select"}, (3)
{"name": "all", "role": "admin"} (4)

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