[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #7976: [DOCS] Small improvements and clarifications around AuthN / AuthZ

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

Jennifer88huang commented on a change in pull request #7976:
URL: https://github.com/apache/pulsar/pull/7976#discussion_r484051888



##########
File path: site2/docs/security-authorization.md
##########
@@ -24,17 +24,17 @@ superUserRoles=my-super-user-1,my-super-user-2
 > A full list of parameters is available in the `conf/broker.conf` file.
 > You can also find the default values for those parameters in [Broker Configuration](reference-configuration.md#broker). 
 
-Typically, you can not only use superuser roles for administrators and clients but also for broker-to-broker authorization. When you use [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other topics of clusters.
+Typically, you use superuser roles for administrators and clients but also for broker-to-broker authorization. When you use [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other topics of clusters.

Review comment:
       usually,  "...not only...but also..." is used  together.
   If you remove "not only", you can also remove "but also" in this sentence.

##########
File path: site2/docs/security-extending.md
##########
@@ -90,9 +90,9 @@ The following is the example for Broker authentication plugins:
 
 ## Authorization
 
-Authorization is the operation that checks whether a particular "role" or "principal" has a permission to perform a certain operation.
+Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
 
-By default, Pulsar provides an embedded authorization, though configuring a different one through a plugin is also an alternative choice.
+By default, Pulsar provides an embedded authorization provider, though configuring a different one through a plugin is also a choice.

Review comment:
       How about the following? You can take it as reference.
   
   By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.

##########
File path: site2/docs/security-authorization.md
##########
@@ -24,17 +24,17 @@ superUserRoles=my-super-user-1,my-super-user-2
 > A full list of parameters is available in the `conf/broker.conf` file.
 > You can also find the default values for those parameters in [Broker Configuration](reference-configuration.md#broker). 
 
-Typically, you can not only use superuser roles for administrators and clients but also for broker-to-broker authorization. When you use [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other topics of clusters.
+Typically, you use superuser roles for administrators and clients but also for broker-to-broker authorization. When you use [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other topics of clusters.
 
-You can also enable the authorization for the proxy in the proxy configuration file (`conf/proxy.conf`). Once you enable the authorization on the proxy, the proxy does an additional authorization check before forwarding the request to a broker. The broker still checks the authorization of the request when the broker receives the forwarded request.
+You can also enable the authorization for the proxy in the proxy configuration file (`conf/proxy.conf`). Once you enable the authorization on the proxy, the proxy does an additional authorization check before forwarding the request to a broker. If authorization is also enabled on the broker, the broker will again check the authorization of the request when the broker receives the forwarded request.

Review comment:
       If you enable authorization on the broker, the broker checks the authorization of the request when the broker receives the forwarded request.

##########
File path: site2/docs/security-extending.md
##########
@@ -10,11 +10,11 @@ Pulsar provides a way to use custom authentication and authorization mechanisms.
 
 Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview.md).
 
-You can choose to use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Broker to validate the credentials.
+You can choose to use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.

Review comment:
       You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.

##########
File path: site2/docs/security-authorization.md
##########
@@ -24,17 +24,17 @@ superUserRoles=my-super-user-1,my-super-user-2
 > A full list of parameters is available in the `conf/broker.conf` file.
 > You can also find the default values for those parameters in [Broker Configuration](reference-configuration.md#broker). 
 
-Typically, you can not only use superuser roles for administrators and clients but also for broker-to-broker authorization. When you use [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other topics of clusters.
+Typically, you use superuser roles for administrators and clients but also for broker-to-broker authorization. When you use [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other topics of clusters.
 
-You can also enable the authorization for the proxy in the proxy configuration file (`conf/proxy.conf`). Once you enable the authorization on the proxy, the proxy does an additional authorization check before forwarding the request to a broker. The broker still checks the authorization of the request when the broker receives the forwarded request.
+You can also enable the authorization for the proxy in the proxy configuration file (`conf/proxy.conf`). Once you enable the authorization on the proxy, the proxy does an additional authorization check before forwarding the request to a broker. If authorization is also enabled on the broker, the broker will again check the authorization of the request when the broker receives the forwarded request.

Review comment:
       use present tense instead of future tense in technical writing.
   For guides, refer to https://developers.google.com/style/tense




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