[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5053: [doc] Improve Pulsar Security-athenz

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

Jennifer88huang commented on a change in pull request #5053: [doc] Improve Pulsar Security-athenz
URL: https://github.com/apache/pulsar/pull/5053#discussion_r318357023
 
 

 ##########
 File path: site2/docs/security-athenz.md
 ##########
 @@ -4,44 +4,44 @@ title: Authentication using Athenz
 sidebar_label: Authentication using Athenz
 ---
 
-[Athenz](https://github.com/yahoo/athenz) is a role-based authentication/authorization system. In Pulsar, Athenz role tokens (aka *z-tokens*) can be used to establish the identify of the client.
+[Athenz](https://github.com/yahoo/athenz) is a role-based authentication/authorization system. In Pulsar, you can use Athenz role tokens (aka *z-tokens*) to establish the identify of the client.
 
 ## Athenz authentication settings
 
-In a [decentralized Athenz system](https://github.com/yahoo/athenz/blob/master/docs/dev_decentralized_access.md) there is both an [authori**Z**ation **M**anagement **S**ystem](https://github.com/yahoo/athenz/blob/master/docs/setup_zms.md) (ZMS) server and an  [authori**Z**ation **T**oken **S**ystem](https://github.com/yahoo/athenz/blob/master/docs/setup_zts.md) (ZTS) server.
+A [decentralized Athenz system](https://github.com/yahoo/athenz/blob/master/docs/dev_decentralized_access.md) contains both an [authori**Z**ation **M**anagement **S**ystem](https://github.com/yahoo/athenz/blob/master/docs/setup_zms.md) (ZMS) server and an  [authori**Z**ation **T**oken **S**ystem](https://github.com/yahoo/athenz/blob/master/docs/setup_zts.md) (ZTS) server.
 
-To begin, you need to set up Athenz service access control. You should create domains for the *provider* (which provides some resources to other services with some authentication/authorization policies) and the *tenant* (which is provisioned to access some resources in a provider). In this case, the provider corresponds to the Pulsar service itself and the tenant corresponds to each application using Pulsar (typically, a [tenant](reference-terminology.md#tenant) in Pulsar).
+To begin, you need to set up Athenz service access control. You need to create domains for the *provider* (which provides some resources to other services with some authentication/authorization policies) and the *tenant* (which is provisioned to access some resources in a provider). In this case, the provider corresponds to the Pulsar service itself and the tenant corresponds to each application using Pulsar (typically, a [tenant](reference-terminology.md#tenant) in Pulsar).
 
 ### Create the tenant domain and service
 
-On the [tenant](reference-terminology.md#tenant) side, you need to:
+On the [tenant](reference-terminology.md#tenant) side, you need to do the follwing things:
 
 1. Create a domain, such as `shopping`
 2. Generate a private/public key pair
 3. Create a service, such as `some_app`, on the domain with the public key
 
-Note that the private key generated in step 2 needs to be specified when the Pulsar client connects to the [broker](reference-terminology.md#broker) (see client configuration examples for [Java](client-libraries-java.md#tls-authentication) and [C++](client-libraries-cpp.md#tls-authentication)).
+Note that you need to specify the private key generated in step 2 when the Pulsar client connects to the [broker](reference-terminology.md#broker) (see client configuration examples for [Java](client-libraries-java.md#tls-authentication) and [C++](client-libraries-cpp.md#tls-authentication)).
 
-For more specific steps involving the Athenz UI, please refer to [this doc](https://github.com/yahoo/athenz/blob/master/docs/example_service_athenz_setup.md#client-tenant-domain).
+For more specific steps involving the Athenz UI, refer to [here](https://github.com/yahoo/athenz/blob/master/docs/example_service_athenz_setup.md#client-tenant-domain).
 
 ### Create the provider domain and add the tenant service to some role members
 
-On the provider side, you need to:
+On the provider side, you need to do the follwing things:
 
 1. Create a domain, such as `pulsar`
 2. Create a role
 3. Add the tenant service to members of the role
 
-Note that in step 2 any action and resource can be specified since they are not used on Pulsar. In other words, Pulsar uses the Athenz role token only for authentication, *not* for authorization.
+Note that you can specify any action and resource in step 2 since they are not used on Pulsar. In other words, Pulsar uses the Athenz role token only for authentication, *not* for authorization.
 
-For more specific steps involving UI, please refer to [this doc](https://github.com/yahoo/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).
+For more specific steps involving UI, refer to [here](https://github.com/yahoo/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).
 
 ## Configure the broker for Athenz
 
-> ### TLS encryption strongly recommended
+> ### TLS encryption 
 >
-> Please note that using TLS encryption is strongly recommended when using Athenz as an authentication provider,
-> as it can protect role tokens from being intercepted and reused (see also [this doc](https://github.com/yahoo/athenz/blob/master/docs/data_model.md)).
+> Note that when you are using Athenz as an authentication provider, you had better use TLS encryption 
+> as it can protect role tokens from being intercepted and reused (for more details involving TLS encrption see [here](https://github.com/yahoo/athenz/blob/master/docs/data_model.md)).
 
 Review comment:
   ```suggestion
   > as it can protect role tokens from being intercepted and reused. For more details on TLS encryption, see [here](https://github.com/yahoo/athenz/blob/master/docs/data_model.md).
   ```

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