[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5070: [doc] Improve Pulsar security authorization

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

Jennifer88huang commented on a change in pull request #5070: [doc] Improve Pulsar security authorization
URL: https://github.com/apache/pulsar/pull/5070#discussion_r319453928
 
 

 ##########
 File path: site2/docs/security-authorization.md
 ##########
 @@ -5,44 +5,42 @@ sidebar_label: Authorization and ACLs
 ---
 
 
-In Pulsar, the [authentication provider](security-overview.md#authentication-providers) is charged with properly identifying clients and
-associating them with [role tokens](security-overview.md#role-tokens). If only authentication is enabled, an authenticated role token will have the ability to access all resources in the cluster. *Authorization* is the process that determines *what* clients are able to do.
+In Pulsar, the [authentication provider](security-overview.md#authentication-providers) is responsible for properly identifying clients and associating the clients with [role tokens](security-overview.md#role-tokens). If you only enable authentication, an authenticated role token has the ability to access all resources in the cluster. *Authorization* is the process that determines *what* clients are able to do.
 
 The role tokens with the most privileges are the *superusers*. The *superusers* can create and destroy tenants, along with having full access to all tenant resources.
 
-When a [tenant](reference-terminology.md#tenant) is created by a superuser, that tenant is assigned an admin role. A client with the admin role token can then create, modify and destroy namespaces, and grant and revoke permissions to *other role tokens* on those namespaces.
+When a superuser creates a [tenant](reference-terminology.md#tenant), that tenant is assigned an admin role. A client with the admin role token can then create, modify and destroy namespaces, and grant and revoke permissions to *other role tokens* on those namespaces.
 
 ## Broker and Proxy Setup
 
-### Enabling Authorization and Assigning Superusers
-
-Authorization is enabled and superusers are assigned in the broker ([`conf/broker.conf`](reference-configuration.md#broker)) configuration files.
+### Enable authorization and assign superusers
+You can enable the authorization and assign the superusers in the broker ([`conf/broker.conf`](reference-configuration.md#broker)) configuration files.
 
 ```properties
 authorizationEnabled=true
 superUserRoles=my-super-user-1,my-super-user-2
 ```
 
-> A full list of parameters available in the `conf/broker.conf` file,
-> as well as the default values for those parameters, can be found in [Broker Configuration](reference-configuration.md#broker) 
+> 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, superuser roles are used for administrators and clients but also for broker-to-broker authorization. When using [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other clusters' topics.
+Typically, you can not only use superuser roles for administrators and clients but also for broker-to-broker authorization. When you are using [geo-replication](concepts-replication.md), every broker needs to be able to publish to all the other topics of clusters.
 
-Authorization can also be enabled for the proxy the proxy configuration file (`conf/proxy.conf`). If it is enabled on the proxy, the proxy will do an additional authorization check before forwarding the request to a broker. The broker will still check the authorization of the request when it 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. The broker still checks the authorization of the request when the broker receives the forwarded request.
 
 ### Proxy Roles
 
-By default, the broker treats the connection between a proxy and the broker as a normal user connection. The user is authenticated as the role configured in ```proxy.conf``` (see ["Enabling TLS Authentication on Proxies"](security-tls-authentication#on-proxies)). However, this is rarely the behaviour that the user desires when connecting to the cluster through a proxy. The user expects to be able to interact with the cluster as the role for which they have authenticated with the proxy.
+By default, the broker treats the connection between a proxy and the broker as a normal user connection. The broker authenticates the user as the role configured in ```proxy.conf``` (see ["Enabling TLS Authentication on Proxies"](security-tls-authentication#on-proxies)). However, when the user is connecting to the cluster through a proxy, the user rarely desires the authentication. The user expects to be able to interact with the cluster as the role for which they have authenticated with the proxy.
 
 Review comment:
   1. if `proxy.conf` is a file name, use `proxy.conf`;
   2. refine "when the user is connecting...." as "when the user connects...";
   3. replace the word "desires".

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