[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325053669
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+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 as the 
follwing:
+
+```
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+Application specifies the token when you create the client instance. An 
alternative is to pass a "token supplier" (a function that returns the token 
when the client library needs one).
+
+>  Always use TLS transport encryption
+> Sending a token is equivalent to sending a password over the wire.You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
+> [Transport Encryption using TLS](security-tls-transport.md) for more details.
+
+
+### CLI tools
+
+[Command-line tools](reference-cli-tools.md) like 
[`pulsar-admin`](reference-pulsar-admin.md), 
[`pulsar-perf`](reference-cli-tools.md#pulsar-perf), and 
[`pulsar-client`](reference-cli-tools.md#pulsar-client) use the 
`conf/client.conf` config file in a Pulsar installation.
+
+You need to add the following parameters to that file to use the token 
authentication with
+CLI tools of Pulsar:
+
+```properties
+webServiceUrl=http://broker.example.com:8080/
+brokerServiceUrl=pulsar://broker.example.com:6650/
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+The token string can also be read from a file, for example:
+
+```
+authParams=file:///path/to/token/file
+```
+
+### Java client
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+
AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")
+.build();
+```
+
+Similarly, you can also pass a `Supplier`:
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+AuthenticationFactory.token(() -> {
+// Read token from custom source
+return readToken();
+})
+.build();
+```
+
+### Python client
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+
authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, with a supplier:
+
+```python
+
+def read_token():
+with open('/path/to/token.txt') as tf:
+return tf.read().strip()
+
+client = Client('pulsar://broker.example.com:6650/'
+authentication=AuthenticationToken(read_token))
+```
+
+### Go client
+
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: 
NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
+})
+```
+
+Alternatively, with a supplier:
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: NewAuthenticationTokenSupplier(func () string {
+// Read token from custom source
+   return readToken()
+   }),
+})
+```
+
+### C++ client
+
+```c++
+#include 
+
+pulsar::ClientConfiguration config;
+config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"));
+
+pulsar::Client client("pulsar://broker.example.com:6650/", config);
+```
+
+## Enable token authentication 
+
+On how to enable token authentication on a Pulsar cluster, you can refer to 
the guide below.
+
+JWT support two different kind of keys in order to generate and validate the 
tokens:
+
+ * Symmetric :
+- You can use a single ***Secret*** key both 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
+
+### Create a

[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325054561
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+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 as the 
follwing:
+
+```
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+Application specifies the token when you create the client instance. An 
alternative is to pass a "token supplier" (a function that returns the token 
when the client library needs one).
+
+>  Always use TLS transport encryption
+> Sending a token is equivalent to sending a password over the wire.You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
+> [Transport Encryption using TLS](security-tls-transport.md) for more details.
+
+
+### CLI tools
+
+[Command-line tools](reference-cli-tools.md) like 
[`pulsar-admin`](reference-pulsar-admin.md), 
[`pulsar-perf`](reference-cli-tools.md#pulsar-perf), and 
[`pulsar-client`](reference-cli-tools.md#pulsar-client) use the 
`conf/client.conf` config file in a Pulsar installation.
+
+You need to add the following parameters to that file to use the token 
authentication with
+CLI tools of Pulsar:
+
+```properties
+webServiceUrl=http://broker.example.com:8080/
+brokerServiceUrl=pulsar://broker.example.com:6650/
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+The token string can also be read from a file, for example:
+
+```
+authParams=file:///path/to/token/file
+```
+
+### Java client
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+
AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")
+.build();
+```
+
+Similarly, you can also pass a `Supplier`:
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+AuthenticationFactory.token(() -> {
+// Read token from custom source
+return readToken();
+})
+.build();
+```
+
+### Python client
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+
authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, with a supplier:
+
+```python
+
+def read_token():
+with open('/path/to/token.txt') as tf:
+return tf.read().strip()
+
+client = Client('pulsar://broker.example.com:6650/'
+authentication=AuthenticationToken(read_token))
+```
+
+### Go client
+
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: 
NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
+})
+```
+
+Alternatively, with a supplier:
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: NewAuthenticationTokenSupplier(func () string {
+// Read token from custom source
+   return readToken()
+   }),
+})
+```
+
+### C++ client
+
+```c++
+#include 
+
+pulsar::ClientConfiguration config;
+config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"));
+
+pulsar::Client client("pulsar://broker.example.com:6650/", config);
+```
+
+## Enable token authentication 
+
+On how to enable token authentication on a Pulsar cluster, you can refer to 
the guide below.
+
+JWT support two different kind of keys in order to generate and validate the 
tokens:
+
+ * Symmetric :
+- You can use a single ***Secret*** key both 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
+
+### Create a

[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325050417
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+A user typically gets a user a token string from the administrator (or some 
automated service).
 
 Review comment:
   ```suggestion
   A user typically gets a token string from the administrator (or some 
automated service).
   ```


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:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325052277
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+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 as the 
follwing:
+
+```
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+Application specifies the token when you create the client instance. An 
alternative is to pass a "token supplier" (a function that returns the token 
when the client library needs one).
+
+>  Always use TLS transport encryption
+> Sending a token is equivalent to sending a password over the wire.You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
+> [Transport Encryption using TLS](security-tls-transport.md) for more details.
+
+
+### CLI tools
+
+[Command-line tools](reference-cli-tools.md) like 
[`pulsar-admin`](reference-pulsar-admin.md), 
[`pulsar-perf`](reference-cli-tools.md#pulsar-perf), and 
[`pulsar-client`](reference-cli-tools.md#pulsar-client) use the 
`conf/client.conf` config file in a Pulsar installation.
+
+You need to add the following parameters to that file to use the token 
authentication with
+CLI tools of Pulsar:
+
+```properties
+webServiceUrl=http://broker.example.com:8080/
+brokerServiceUrl=pulsar://broker.example.com:6650/
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+The token string can also be read from a file, for example:
+
+```
+authParams=file:///path/to/token/file
+```
+
+### Java client
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+
AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")
+.build();
+```
+
+Similarly, you can also pass a `Supplier`:
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+AuthenticationFactory.token(() -> {
+// Read token from custom source
+return readToken();
+})
+.build();
+```
+
+### Python client
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+
authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, with a supplier:
 
 Review comment:
   refine this sentence, and 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:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325051249
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+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 as the 
follwing:
+
+```
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+Application specifies the token when you create the client instance. An 
alternative is to pass a "token supplier" (a function that returns the token 
when the client library needs one).
+
+>  Always use TLS transport encryption
+> Sending a token is equivalent to sending a password over the wire.You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
 
 Review comment:
   replace "talk" with another word.


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:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325053148
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+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 as the 
follwing:
+
+```
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+Application specifies the token when you create the client instance. An 
alternative is to pass a "token supplier" (a function that returns the token 
when the client library needs one).
+
+>  Always use TLS transport encryption
+> Sending a token is equivalent to sending a password over the wire.You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
+> [Transport Encryption using TLS](security-tls-transport.md) for more details.
+
+
+### CLI tools
+
+[Command-line tools](reference-cli-tools.md) like 
[`pulsar-admin`](reference-pulsar-admin.md), 
[`pulsar-perf`](reference-cli-tools.md#pulsar-perf), and 
[`pulsar-client`](reference-cli-tools.md#pulsar-client) use the 
`conf/client.conf` config file in a Pulsar installation.
+
+You need to add the following parameters to that file to use the token 
authentication with
+CLI tools of Pulsar:
+
+```properties
+webServiceUrl=http://broker.example.com:8080/
+brokerServiceUrl=pulsar://broker.example.com:6650/
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+The token string can also be read from a file, for example:
+
+```
+authParams=file:///path/to/token/file
+```
+
+### Java client
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+
AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")
+.build();
+```
+
+Similarly, you can also pass a `Supplier`:
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+AuthenticationFactory.token(() -> {
+// Read token from custom source
+return readToken();
+})
+.build();
+```
+
+### Python client
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+
authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, with a supplier:
+
+```python
+
+def read_token():
+with open('/path/to/token.txt') as tf:
+return tf.read().strip()
+
+client = Client('pulsar://broker.example.com:6650/'
+authentication=AuthenticationToken(read_token))
+```
+
+### Go client
+
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: 
NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
+})
+```
+
+Alternatively, with a supplier:
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: NewAuthenticationTokenSupplier(func () string {
+// Read token from custom source
+   return readToken()
+   }),
+})
+```
+
+### C++ client
+
+```c++
+#include 
+
+pulsar::ClientConfiguration config;
+config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"));
+
+pulsar::Client client("pulsar://broker.example.com:6650/", config);
+```
+
+## Enable token authentication 
+
+On how to enable token authentication on a Pulsar cluster, you can refer to 
the guide below.
+
+JWT support two different kind of keys in order to generate and validate the 
tokens:
+
+ * Symmetric :
+- You can use a single ***Secret*** key both 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
 
 Review comment:
   ```suggestion
   - You can use ***Private***

[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325053195
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+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 as the 
follwing:
+
+```
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+Application specifies the token when you create the client instance. An 
alternative is to pass a "token supplier" (a function that returns the token 
when the client library needs one).
+
+>  Always use TLS transport encryption
+> Sending a token is equivalent to sending a password over the wire.You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
+> [Transport Encryption using TLS](security-tls-transport.md) for more details.
+
+
+### CLI tools
+
+[Command-line tools](reference-cli-tools.md) like 
[`pulsar-admin`](reference-pulsar-admin.md), 
[`pulsar-perf`](reference-cli-tools.md#pulsar-perf), and 
[`pulsar-client`](reference-cli-tools.md#pulsar-client) use the 
`conf/client.conf` config file in a Pulsar installation.
+
+You need to add the following parameters to that file to use the token 
authentication with
+CLI tools of Pulsar:
+
+```properties
+webServiceUrl=http://broker.example.com:8080/
+brokerServiceUrl=pulsar://broker.example.com:6650/
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+The token string can also be read from a file, for example:
+
+```
+authParams=file:///path/to/token/file
+```
+
+### Java client
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+
AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")
+.build();
+```
+
+Similarly, you can also pass a `Supplier`:
+
+```java
+PulsarClient client = PulsarClient.builder()
+.serviceUrl("pulsar://broker.example.com:6650/")
+.authentication(
+AuthenticationFactory.token(() -> {
+// Read token from custom source
+return readToken();
+})
+.build();
+```
+
+### Python client
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+
authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, with a supplier:
+
+```python
+
+def read_token():
+with open('/path/to/token.txt') as tf:
+return tf.read().strip()
+
+client = Client('pulsar://broker.example.com:6650/'
+authentication=AuthenticationToken(read_token))
+```
+
+### Go client
+
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: 
NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
+})
+```
+
+Alternatively, with a supplier:
+
+```go
+client, err := NewClient(ClientOptions{
+   URL:"pulsar://localhost:6650",
+   Authentication: NewAuthenticationTokenSupplier(func () string {
+// Read token from custom source
+   return readToken()
+   }),
+})
+```
+
+### C++ client
+
+```c++
+#include 
+
+pulsar::ClientConfiguration config;
+config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"));
+
+pulsar::Client client("pulsar://broker.example.com:6650/", config);
+```
+
+## Enable token authentication 
+
+On how to enable token authentication on a Pulsar cluster, you can refer to 
the guide below.
+
+JWT support two different kind of keys in order to generate and validate the 
tokens:
+
+ * Symmetric :
+- You can use a single ***Secret*** key both 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
 
 Review comme

[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325051095
 
 

 ##
 File path: site2/docs/security-jwt.md
 ##
 @@ -0,0 +1,243 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: Authentication using JWT
+---
+
+## 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)).
+
+You can use tokens to identify a Pulsar client and associate with some 
"principal" (or "role") that
+is permitted to do some actions (eg: publish to a topic or consume from a 
topic).
+
+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 as the 
follwing:
+
+```
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
+```
+
+Application specifies the token when you create the client instance. An 
alternative is to pass a "token supplier" (a function that returns the token 
when the client library needs one).
+
+>  Always use TLS transport encryption
+> Sending a token is equivalent to sending a password over the wire.You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
 
 Review comment:
   ```suggestion
   > Sending a token is equivalent to sending a password over the wire. You had 
better use TLS encryption all the time when you talk to the Pulsar service. See
   ```


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:
us...@infra.apache.org


With regards,
Apache Git Services


[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] Adjust the content structure of the security chapter

2019-09-17 Thread GitBox
Jennifer88huang commented on a change in pull request #5201: [Issue 5050][Docs] 
Adjust the content structure of the security chapter 
URL: https://github.com/apache/pulsar/pull/5201#discussion_r325046390
 
 

 ##
 File path: site2/docs/security-overview.md
 ##
 @@ -10,26 +10,27 @@ By default, Pulsar configures no encryption, 
authentication, or authorization. A
 
 Pulsar supports a pluggable authentication mechanism. And Pulsar clients use 
this mechanism to authenticate with brokers and proxies. You can also configure 
Pulsar to support multiple authentication sources.
 
-You'd better secure the service components in your Apache Pulsar deployment.
+You had better secure the service components in your Apache Pulsar deployment.
 
-## Role Tokens
+## Role tokens
 
-In Pulsar, a *role* is a string, like `admin` or `app1`, which can represent 
one or more clients. You can use roles to control permission for clients to 
produce or consume from certain topics, administer the configuration for 
tenants, and so on.
+In Pulsar, a *role* is a string, like `admin` or `app1`, which can represent a 
single client or multiple clients. You can use roles to control permission for 
clients to produce or consume from certain topics, administer the configuration 
for tenants, and so on.
 
-Apache Pulsar uses the [Authentication Provider](#authentication-providers) to 
establish the identity of a client and then assign a *role token* to that 
client. This role token is then used for [Authorization and 
ACLs](security-authorization.md) to determine what the client is authorized to 
do.
+Apache Pulsar uses a [Authentication Provider](#authentication-providers) to 
establish the identity of a client and then assign a *role token* to that 
client. This role token is then used for [Authorization and 
ACLs](security-authorization.md) to determine what the client is authorized to 
do.
 
-## Authentication Providers
+## Authentication providers
 
 Currently Pulsar supports the following authentication providers:
 
 - [TLS Authentication](security-tls-authentication.md)
 - [Athenz](security-athenz.md)
 - [Kerberos](security-kerberos.md)
-- JSON Web Token Authentication
+- [JSON Web Token Authentication](security-jwt.md)
 
 ## Contents
 
 Review comment:
   Why should we add those lists here?


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:
us...@infra.apache.org


With regards,
Apache Git Services