Rule-Based Authorization Plugins

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. 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 differs in how the user’s roles are obtained:

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.

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

User’s roles may either come from the request itself, then you will use the ExternalRoleRuleBasedAuthorizationPlugin variant of RBAC. If you need to hardcode user-role mappings, then you need to use the RuleBasedAuthorizationPlugin and define the user-role mappings in security.json like this:

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", 
    "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"}
    ]
  }
}

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", 
   "jwksUrl": "https://my.key.server/jwk.json", 
   "rolesClaim": "roles" 
},
"authorization":{
   "class":"solr.ExternalRoleRuleBasedAuthorizationPlugin", 
   "permissions":[{"name":"security-edit",
      "role":"admin"}] 
}}

Let’s walk through this example:

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

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:

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:

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:

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

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

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:

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