Jennifer88huang commented on a change in pull request #5052: [doc] Improve Pulsar Security-token-admin URL: https://github.com/apache/pulsar/pull/5052#discussion_r319390787
########## File path: site2/docs/security-token-admin.md ########## @@ -6,96 +6,87 @@ sidebar_label: Token authentication admin ## Token Authentication Overview -Pulsar supports authenticating clients using security tokens that are based on -[JSON Web Tokens](https://jwt.io/introduction/) ([RFC-7519](https://tools.ietf.org/html/rfc7519)). +Pulsar supports authenticating clients using security tokens that are based on [JSON Web Tokens](https://jwt.io/introduction/) ([RFC-7519](https://tools.ietf.org/html/rfc7519)). -Tokens are used to identify a Pulsar client and associate with some "principal" (or "role") which -will be then granted permissions to do some actions (eg: publish or consume from a topic). +You can use tokens to identify a Pulsar client and associate with some "principal" (or "role") that +is permitted to do some actions (for example, publish to a topic or consume from a topic). -A user will typically be given a token string by an administrator (or some automated service). +A user typically gets a user a token string from the administrator (or some automated service). -The compact representation of a signed JWT is a string that looks like: +The compact representation of a signed JWT is a string that looks like as the follwing: ``` - eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY - ``` +eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY +``` + +Application specifies the token when you are creating the client instance. An alternative is to pass a "token supplier" (a function that returns the token when the client library needs one). -Application will specify the token when creating the client instance. An alternative is to pass -a "token supplier", that is to say a function that returns the token when the client library -will need one. > #### Always use TLS transport encryption -> Sending a token is equivalent to sending a password over the wire. It is strongly recommended to -> always use TLS encryption when talking to the Pulsar service. See -> [Transport Encryption using TLS](security-tls-transport.md) +> Sending a token is equivalent to sending a password over the wire. You had better +> use TLS encryption all the time when you are talking to the Pulsar service. See +> [Transport Encryption using TLS](security-tls-transport.md) for more details. ## Secret vs Public/Private keys JWT support two different kind of keys in order to generate and validate the tokens: * Symmetric : - - there is a single ***Secret*** key that is used both to generate and validate - * Asymmetric: there is a pair of keys. - - ***Private*** key is used to generate tokens - - ***Public*** key is used to validate tokens + - You can use a single ***Secret*** key to generate and validate tokens. + * Asymmetric: A pair of keys consist of the Private key and the Public key. + - You can use ***Private*** key to generate tokens + - You can use ***Public*** key to validate tokens ### Secret key -When using a secret key, the administrator will create the key and he will -use it to generate the client tokens. This key will be also configured to -the brokers to allow them to validate the clients. +When you are using a secret key, the administrator creates the key and uses the key to generate the client tokens. You can also configure this key to the brokers in order to allow the brokers validating the clients. Review comment: Use present tense, for example, "when you use a xxx". Check all similar cases. ---------------------------------------------------------------- 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: [email protected] With regards, Apache Git Services
