You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/09/13 10:39:44 UTC
[GitHub] [pulsar] momo-jun opened a new pull request, #17615: [improve][doc] Improve the information architecture of the security chapter
momo-jun opened a new pull request, #17615:
URL: https://github.com/apache/pulsar/pull/17615
### Motivation
Improve the doc set of the `Security` chapter to provide Pulsar users with a more accurate, easy-to-read, and comprehensive information experience.
### Modifications
This PR is a quick change to the overall IA, and more detailed changes will be included in a follow-up PR.
1. Group encryption- and authentication-related topics in the sidebar.
2. Move `TLS encryption/authentication using Keystore` sections to related parent topics, and remove `Use TLS with KeyStore` topic.
3. Streamline the headings of authentication topics.
4. Use language tabs to group code snippets throughout the security chapter.
5. Remove the java code snippets from java client page, and add links to individual authentication topic - fix #17561.
Preview looks good. I've checked all the topics and here is one of the screenshots.
<img width="1732" alt="image" src="https://user-images.githubusercontent.com/60642177/189880577-01da5eb3-d4c7-404f-9457-97096c99afea.png">
### Documentation
- [ ] `doc`
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] momo-jun commented on a diff in pull request #17615: [improve][doc] Improve the information architecture of the security chapter
Posted by GitBox <gi...@apache.org>.
momo-jun commented on code in PR #17615:
URL: https://github.com/apache/pulsar/pull/17615#discussion_r970391607
##########
site2/docs/security-athenz.md:
##########
@@ -65,13 +65,41 @@ brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":
> A full listing 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).
-## Configure clients for Athenz
+## Configure Athenz authentication in Pulsar clients
-For more information on Pulsar client authentication using Athenz, see the following language-specific docs:
+To use Athenz as an authentication provider, you need to [use TLS](#tls-authentication.md) and provide values for four parameters in a hash:
+* `tenantDomain`
+* `tenantService`
+* `providerDomain`
+* `privateKey`
-* [Java client](client-libraries-java.md#athenz)
+You can also set an optional `keyId`. The following is an example.
-## Configure CLI tools for Athenz
+```java
+Map<String, String> authParams = new HashMap();
+authParams.put("tenantDomain", "shopping"); // Tenant domain name
+authParams.put("tenantService", "some_app"); // Tenant service name
+authParams.put("providerDomain", "pulsar"); // Provider domain name
+authParams.put("privateKey", "file:///path/to/private.pem"); // Tenant private key path
+authParams.put("keyId", "v1"); // Key id for the tenant private key (optional, default: "0")
+
+Authentication athenzAuth = AuthenticationFactory
+ .create(AuthenticationAthenz.class.getName(), authParams);
+
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar+ssl://my-broker.com:6651")
+ .tlsTrustCertsFilePath("/path/to/cacert.pem")
+ .authentication(athenzAuth)
+ .build();
+```
+
+#### Supported pattern formats
Review Comment:
It's copied and pasted here from another topic. I guess the intention was kind of to be a reference sub-topic so that's why `####` was used (not shown in the hot links). Thanks for the reminder. It will be evaluated in a further review throughout the topic.
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] nodece commented on a diff in pull request #17615: [improve][doc] Improve the information architecture of the security chapter
Posted by GitBox <gi...@apache.org>.
nodece commented on code in PR #17615:
URL: https://github.com/apache/pulsar/pull/17615#discussion_r970281496
##########
site2/docs/security-tls-transport.md:
##########
@@ -324,3 +322,258 @@ var client = PulsarClient.Builder()
```
> Note that `VerifyCertificateName` refers to the configuration of hostname verification in the C# client.
+
+</TabItem>
+</Tabs>
+````
+
+## Configure TLS encryption using CLI tools
Review Comment:
```suggestion
## Configure TLS encryption in CLI tools
```
##########
site2/docs/security-jwt.md:
##########
@@ -282,3 +163,122 @@ brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0
```
The proxy uses its own token when connecting to brokers. You need to configure the role token for this key pair in the `proxyRoles` of the brokers. For more details, see [authorization](security-authorization.md).
+
+### Configure JWT authentication in CLI Tools
+
+[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](/tools/pulsar-admin/), [`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:
+
+```conf
+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:
+
+```conf
+authParams=file:///path/to/token/file
+```
+
+### Configure JWT authentication in Pulsar clients
+
+You can use tokens to authenticate the following Pulsar clients.
+
+````mdx-code-block
+<Tabs groupId="lang-choice"
+ defaultValue="Java"
+ values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"Go","value":"Go"},{"label":"C++","value":"C++"},{"label":"C#","value":"C#"}]}>
+<TabItem value="Java">
+
+```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();
+```
+
+</TabItem>
+<TabItem value="Python">
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+ authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, you can also pass 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))
+```
+
+</TabItem>
+<TabItem value="Go">
+
+```go
+client, err := NewClient(ClientOptions{
+ URL: "pulsar://localhost:6650",
+ Authentication: NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
+})
+```
+
+Similarly, you can also pass a `Supplier`:
+
+```go
+client, err := NewClient(ClientOptions{
+ URL: "pulsar://localhost:6650",
+ Authentication: NewAuthenticationTokenSupplier(func () string {
Review Comment:
```suggestion
Authentication: pulsar.NewAuthenticationTokenSupplier(func () string {
```
##########
site2/docs/security-jwt.md:
##########
@@ -282,3 +163,122 @@ brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0
```
The proxy uses its own token when connecting to brokers. You need to configure the role token for this key pair in the `proxyRoles` of the brokers. For more details, see [authorization](security-authorization.md).
+
+### Configure JWT authentication in CLI Tools
+
+[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](/tools/pulsar-admin/), [`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:
+
+```conf
+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:
+
+```conf
+authParams=file:///path/to/token/file
+```
+
+### Configure JWT authentication in Pulsar clients
+
+You can use tokens to authenticate the following Pulsar clients.
+
+````mdx-code-block
+<Tabs groupId="lang-choice"
+ defaultValue="Java"
+ values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"Go","value":"Go"},{"label":"C++","value":"C++"},{"label":"C#","value":"C#"}]}>
+<TabItem value="Java">
+
+```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();
+```
+
+</TabItem>
+<TabItem value="Python">
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+ authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, you can also pass 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))
+```
+
+</TabItem>
+<TabItem value="Go">
+
+```go
+client, err := NewClient(ClientOptions{
+ URL: "pulsar://localhost:6650",
+ Authentication: NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
+})
+```
+
+Similarly, you can also pass a `Supplier`:
+
+```go
+client, err := NewClient(ClientOptions{
Review Comment:
```suggestion
client, err := pulsar.NewClient(pulsar.ClientOptions{
```
##########
site2/docs/security-jwt.md:
##########
@@ -282,3 +163,122 @@ brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0
```
The proxy uses its own token when connecting to brokers. You need to configure the role token for this key pair in the `proxyRoles` of the brokers. For more details, see [authorization](security-authorization.md).
+
+### Configure JWT authentication in CLI Tools
+
+[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](/tools/pulsar-admin/), [`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:
+
+```conf
+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:
+
+```conf
+authParams=file:///path/to/token/file
+```
+
+### Configure JWT authentication in Pulsar clients
+
+You can use tokens to authenticate the following Pulsar clients.
+
+````mdx-code-block
+<Tabs groupId="lang-choice"
+ defaultValue="Java"
+ values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"Go","value":"Go"},{"label":"C++","value":"C++"},{"label":"C#","value":"C#"}]}>
+<TabItem value="Java">
+
+```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();
+```
+
+</TabItem>
+<TabItem value="Python">
+
+```python
+from pulsar import Client, AuthenticationToken
+
+client = Client('pulsar://broker.example.com:6650/'
+ authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))
+```
+
+Alternatively, you can also pass 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))
+```
+
+</TabItem>
+<TabItem value="Go">
+
+```go
+client, err := NewClient(ClientOptions{
Review Comment:
```suggestion
client, err := pulsar.NewClient(pulsar.ClientOptions{
```
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Anonymitaet commented on a diff in pull request #17615: [improve][doc] Improve the information architecture of the security chapter
Posted by GitBox <gi...@apache.org>.
Anonymitaet commented on code in PR #17615:
URL: https://github.com/apache/pulsar/pull/17615#discussion_r970282369
##########
site2/docs/security-athenz.md:
##########
@@ -65,13 +65,41 @@ brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":
> A full listing 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).
-## Configure clients for Athenz
+## Configure Athenz authentication in Pulsar clients
-For more information on Pulsar client authentication using Athenz, see the following language-specific docs:
+To use Athenz as an authentication provider, you need to [use TLS](#tls-authentication.md) and provide values for four parameters in a hash:
+* `tenantDomain`
+* `tenantService`
+* `providerDomain`
+* `privateKey`
-* [Java client](client-libraries-java.md#athenz)
+You can also set an optional `keyId`. The following is an example.
-## Configure CLI tools for Athenz
+```java
+Map<String, String> authParams = new HashMap();
+authParams.put("tenantDomain", "shopping"); // Tenant domain name
+authParams.put("tenantService", "some_app"); // Tenant service name
+authParams.put("providerDomain", "pulsar"); // Provider domain name
+authParams.put("privateKey", "file:///path/to/private.pem"); // Tenant private key path
+authParams.put("keyId", "v1"); // Key id for the tenant private key (optional, default: "0")
+
+Authentication athenzAuth = AuthenticationFactory
+ .create(AuthenticationAthenz.class.getName(), authParams);
+
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar+ssl://my-broker.com:6651")
+ .tlsTrustCertsFilePath("/path/to/cacert.pem")
+ .authentication(athenzAuth)
+ .build();
+```
+
+#### Supported pattern formats
Review Comment:
1. `###` instead of `####`?
2. Other headings are in the format of "Verb + xxx" while this heading is not.
Consider keeping consistent or turning this section into other content formats (like moving lines 97 - 100 to line 74)?
So that users know the relationship between the section `Configure Athenz authentication in Pulsar clients` and `Supported pattern formats`
(the info in `Supported pattern format` can be a part of `Configure Athenz authentication in Pulsar clients` )
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] nodece commented on a diff in pull request #17615: [improve][doc] Improve the information architecture of the security chapter
Posted by GitBox <gi...@apache.org>.
nodece commented on code in PR #17615:
URL: https://github.com/apache/pulsar/pull/17615#discussion_r969821537
##########
site2/docs/client-libraries-java.md:
##########
@@ -1258,88 +1258,14 @@ For examples of ProtobufNativeSchema, see [`SchemaDefinition` in `Complex type`]
## Authentication
-Pulsar currently supports three authentication schemes: [TLS](security-tls-authentication.md), [Athenz](security-athenz.md), and [Oauth2](security-oauth2.md). You can use the Pulsar Java client with all of them.
+Pulsar currently supports three authentication providers:
+* [TLS](security-tls-authentication.md#configure-tls-authentication-in-pulsar-clients)
+* [JWT](security-jwt.md#configure-jwt-authentication-in-pulsar-clients)
+* [Athenz](security-athenz.md#configure-athenz-authentication-in-pulsar-clients)
+* [Kerberos](security-kerberos.md#java-client-and-java-admin-client)
+* [Oauth2](security-oauth2.md#configure-oauth2-authentication-in-pulsar-clients)
Review Comment:
```suggestion
* [OAuth2](security-oauth2.md#configure-oauth2-authentication-in-pulsar-clients)
```
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] momo-jun commented on pull request #17615: [improve][doc] Improve the information architecture of the security chapter
Posted by GitBox <gi...@apache.org>.
momo-jun commented on PR #17615:
URL: https://github.com/apache/pulsar/pull/17615#issuecomment-1248921132
@daveduggins This is the improvement I mentioned on this Wednesday. Feel free to take a look and comment.
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] momo-jun merged pull request #17615: [improve][doc] Improve the information architecture of the security chapter
Posted by GitBox <gi...@apache.org>.
momo-jun merged PR #17615:
URL: https://github.com/apache/pulsar/pull/17615
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] momo-jun commented on pull request #17615: [improve][doc] Improve the information architecture of the security chapter
Posted by GitBox <gi...@apache.org>.
momo-jun commented on PR #17615:
URL: https://github.com/apache/pulsar/pull/17615#issuecomment-1246324887
@nodece thanks for the review. Your comments have been addressed.
--
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.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org