[GitHub] [lucene-solr] ctargett commented on a change in pull request #924: SOLR-13820: Improve RBAP documentation

[GitBox <gi...@apache.org>]

ctargett commented on a change in pull request #924: SOLR-13820: Improve RBAP documentation
URL: https://github.com/apache/lucene-solr/pull/924#discussion_r332017837
 
 

 ##########
 File path: solr/solr-ref-guide/src/rule-based-authorization-plugin.adoc
 ##########
 @@ -16,65 +16,154 @@
 // 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
+== 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.
 
-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>>.
+== Configuring the Rule-Based Authorization Plugin
 
-This file has two parts, the `authentication` part and the `authorization` part. The `authentication` part stores information about the class being used for authentication.
+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.
 
-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.
+In addition to manual edits to `security.json`, Solr offers an <<Authorization API>> for modifying RBAP configuration.
 
 Review comment:
   I feel like we should discourage manual editing of `security.json`, because there is a bit of subtlety to getting it to work (specifically, removing the version information before uploading the edited file). The section you link to in the previous bullet point explains this (assuming someone reads that far), but this line implies to me that manual edit vs API is just a matter of preference. To make sure we aren't being confusing, IMO we should either reinforce here that manual editing should be done carefully, or choose to focus only on using the API.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org