[improve][doc] Improve the information architecture of the security c…

…hapter (#17615) * Sidebar re-org * Separate TLS encryption/authentication using Keystore to parent topics * use language-specific tabs to show code snippets * streamline headings * Update client-libraries-java.md * Add code snippet for python clients to support #17482 * Add code snippet for go clients
apache · Sep 20, 2022 · 3d35448 · 3d35448
1 parent 4af8bf0
commit 3d35448
Show file tree

Hide file tree

Showing 10 changed files with 702 additions and 676 deletions.
diff --git a/site2/docs/client-libraries-java.md b/site2/docs/client-libraries-java.md
@@ -1258,92 +1258,18 @@ 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 the following authentication mechansims:
+* [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)
+* [HTTP basic](security-basic-auth.md#configure-basic-authentication-in-pulsar-clients)
 
-### TLS Authentication
-
-To use [TLS](security-tls-authentication.md), `enableTls` method is deprecated and you need to use "pulsar+ssl://" in serviceUrl to enable, point your Pulsar client to a TLS cert path, and provide paths to cert and key files.
-
-The following is an example.
-
-```java
-Map<String, String> authParams = new HashMap();
-authParams.put("tlsCertFile", "/path/to/client-cert.pem");
-authParams.put("tlsKeyFile", "/path/to/client-key.pem");
-
-Authentication tlsAuth = AuthenticationFactory
-        .create(AuthenticationTls.class.getName(), authParams);
-
-PulsarClient client = PulsarClient.builder()
-        .serviceUrl("pulsar+ssl://my-broker.com:6651")
-        .tlsTrustCertsFilePath("/path/to/cacert.pem")
-        .authentication(tlsAuth)
-        .build();
-```
-
-### Athenz
-
-To use [Athenz](security-athenz.md) 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`
-
-You can also set an optional `keyId`. The following is an example.
-
-```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
-The `privateKey` parameter supports the following three pattern formats:
-* `file:///path/to/file`
-* `file:/path/to/file`
-* `data:application/x-pem-file;base64,<base64-encoded value>`
-
-### Oauth2
-
-The following example shows how to use [Oauth2](security-oauth2.md) as an authentication provider for the Pulsar Java client.
-
-You can use the factory method to configure authentication for Pulsar Java client.
-
-```java
-PulsarClient client = PulsarClient.builder()
-    .serviceUrl("pulsar://broker.example.com:6650/")
-    .authentication(
-        AuthenticationFactoryOAuth2.clientCredentials(this.issuerUrl, this.credentialsUrl, this.audience))
-    .build();
-```
-
-In addition, you can also use the encoded parameters to configure authentication for Pulsar Java client.
-
-```java
-Authentication auth = AuthenticationFactory
-    .create(AuthenticationOAuth2.class.getName(), "{"type":"client_credentials","privateKey":"...","issuerUrl":"...","audience":"..."}");
-PulsarClient client = PulsarClient.builder()
-    .serviceUrl("pulsar://broker.example.com:6650/")
-    .authentication(auth)
-    .build();
-```
 
 ## Cluster-level failover
 
-For more concepts and reference information about cluster-level failover, including concept, benefits, use cases, constraints, usage and working principles, see [Cluster-level failover](concepts-cluster-level-failover.md). 
+For more concepts and reference information about cluster-level failover, including concepts, benefits, use cases, constraints, usage and working principles, see [Cluster-level failover](concepts-cluster-level-failover.md). 
 
 :::tip
 

diff --git a/site2/docs/security-athenz.md b/site2/docs/security-athenz.md
@@ -4,9 +4,9 @@ title: Authentication using Athenz
 sidebar_label: "Authentication using Athenz"
 ---
 
-[Athenz](https://github.com/AthenZ/athenz) is a role-based authentication/authorization system. In Pulsar, you can use Athenz role tokens (also known as *z-tokens*) to establish the identify of the client.
+[Athenz](https://github.com/AthenZ/athenz) is a role-based authentication/authorization system. In Pulsar, you can use Athenz role tokens (also known as *z-tokens*) to establish the identity of the client.
 
-## Athenz authentication settings
+## Enable Athenz authentication
 
 A [decentralized Athenz system](https://github.com/AthenZ/athenz/blob/master/docs/decent_authz_flow.md) contains an [authori**Z**ation **M**anagement **S**ystem](https://github.com/AthenZ/athenz/blob/master/docs/setup_zms.md) (ZMS) server and an [authori**Z**ation **T**oken **S**ystem](https://github.com/AthenZ/athenz/blob/master/docs/setup_zts) (ZTS) server.
 
@@ -36,7 +36,7 @@ Note that you can specify any action and resource in step 2 since they are not u
 
 For more specific steps involving UI, refer to [Example Service Access Control Setup](https://github.com/AthenZ/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).
 
-## Configure the broker for Athenz
+## Enable Athenz authentication on brokers
 
 > ### TLS encryption 
 >
@@ -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
+The `privateKey` parameter supports the following three pattern formats:
+* `file:///path/to/file`
+* `file:/path/to/file`
+* `data:application/x-pem-file;base64,<base64-encoded value>`
+
+## Configure Athenz 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.
 

diff --git a/site2/docs/security-basic-auth.md b/site2/docs/security-basic-auth.md
@@ -129,8 +129,11 @@ authParams={"userId":"superuser","password":"admin"}
 
 The following example shows how to configure basic authentication when using Pulsar clients.
 
-<Tabs>
-  <TabItem value="Java" label="Java" default>
+````mdx-code-block
+<Tabs groupId="lang-choice"
+  defaultValue="Java"
+  values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"C++","value":"C++"},{"label":"Go","value":"Go"}]}>
+<TabItem value="Java">
 
    ```java
    AuthenticationBasic auth = new AuthenticationBasic();
@@ -142,7 +145,7 @@ The following example shows how to configure basic authentication when using Pul
    ```
 
   </TabItem>
-  <TabItem value="C++" label="C++" default>
+  <TabItem value="C++">
 
    ```cpp
    #include <pulsar/Client.h>
@@ -158,4 +161,26 @@ The following example shows how to configure basic authentication when using Pul
    ```
 
   </TabItem>
+  <TabItem value="Python">
+
+   ```python
+   if __name__ == "__main__":
+      client = Client("pulsar://broker.example.com:6650", authentication=AuthenticationBasic("admin", "123456"))
+   ```
+
+  </TabItem>
+  <TabItem value="Go">
+
+   ```go
+	provider, err := pulsar.NewAuthenticationBasic("admin", "123456")
+	if err != nil {
+		log.Fatal(err)
+	}
+	client, err := pulsar.NewClient(pulsar.ClientOptions{
+		URL: "pulsar://broker.example.com:6650",
+		Authentication: provider,
+	})
+   ```
+
+  </TabItem>
 </Tabs>