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 in ZooKeeper. This means this feature is available when using Solr in SolrCloud mode only.
Enable the Authorization Plugin
The plugin must be enabled in
security.json. This file and how to upload it to ZooKeeper is described in detail in the section 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.
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.
security.json shows how the Basic authentication plugin can work with this authorization plugin:
There are several things defined in this example:
- Basic authentication and rule-based authorization plugins are enabled.
- A user called 'solr', with a password has been defined.
- 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.
- The 'admin' role has been defined, and it has permission to edit security settings.
- The 'solr' user has been defined to the 'admin' role.
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.
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:
- security-edit: this permission is allowed to edit the security configuration, meaning any update action that modifies
security.jsonthrough the APIs will be allowed.
- security-read: this permission is allowed to read the security configuration, meaning any action that reads
security.jsonsettings 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.
- core-admin-read : Read operations on the core admin API
- core-admin-edit: Core admin commands that can mutate the system state.
- 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.
- 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:
- 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:
- update: this permission is allowed to perform any update action on any collection. This includes sending documents for indexing (using an update request handler).
- read: this permission is allowed to perform any read action on any collection. This includes querying using search handlers (using request handlers) such as
- all: Any requests coming to Solr.
/admin/authorization: takes a set of commands to create permissions, map permissions to roles, and map roles to users.
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.
Permissions need to be created if they are not on the list of pre-defined permissions above.
Several properties can be used to define your custom permission.
|name||The name of the permission. This is required only if it is a predefined permission.|
The collection or collections the permission will apply to.
When the path that will be allowed is collection-specific, such as when setting permissions to allow useof the Schema API, omitting the collection property will allow the defined path and/or method for all collections. However, when the path is one that is non-collection-specific, such as the Collections API, the collection value must be
|path||A request handler name, such as |
|method||HTTP methods that are allowed for this permission. You could allow only GET requests, or have a role that allows PUT and POST requests. The method values that are allowed for this property are GET, POST, PUT,DELETEand HEAD.|
The names and values of request parameters. This property can be omitted if all request parameters are to be matched, but will restrict access only to the values provided if defined.
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:
The value of the parameter can be a simple string or it could be a regular expression. use the prefix
If the commands LIST and CLUSTERSTATUS are case insensitive, the above example should be as follows
|before||This property allows ordering of permissions. The value of this property is the index of the permission that this new permission should be placed before in |
|role||The name of the role(s) to give this permission. This name will be used to map user IDs to the role to grant these permissions. The value can be wildcard such as (|
The following would create 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.
update or delete permissions
Permissions can be accessed using their index in the list. Use the GET /security/authorization to see the existing permissions and their indices.
the following example updates the
'role' attribute of permission at index
the following example deletes permission at index
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":