You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by li...@apache.org on 2021/11/08 08:30:17 UTC
[pulsar] branch master updated: [website][upgrade]feat: docs
migration - 2.7.1 / security (#12610)
This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 5382c68 [website][upgrade]feat: docs migration - 2.7.1 / security (#12610)
5382c68 is described below
commit 5382c68c70f1c98e0446add1b21a04f8f4a33f3d
Author: Li Li <ur...@gmail.com>
AuthorDate: Mon Nov 8 16:29:21 2021 +0800
[website][upgrade]feat: docs migration - 2.7.1 / security (#12610)
* [website][upgrade]feat: docs migration - 2.7.1 / deploy
Signed-off-by: LiLi <ur...@gmail.com>
* [website][upgrade]feat: docs migration - 2.7.1 / administration
Signed-off-by: LiLi <ur...@gmail.com>
* [website][upgrade]feat: docs migration - 2.7.1 / security
Signed-off-by: LiLi <ur...@gmail.com>
---
.../version-2.7.1/security-athenz.md | 102 +++++
.../version-2.7.1/security-authorization.md | 118 ++++++
.../version-2.7.1/security-bouncy-castle.md | 161 ++++++++
.../version-2.7.1/security-encryption.md | 194 +++++++++
.../version-2.7.1/security-extending.md | 211 ++++++++++
.../versioned_docs/version-2.7.1/security-jwt.md | 344 ++++++++++++++++
.../version-2.7.1/security-kerberos.md | 447 +++++++++++++++++++++
.../version-2.7.1/security-oauth2.md | 231 +++++++++++
.../version-2.7.1/security-overview.md | 39 ++
.../version-2.7.1/security-tls-authentication.md | 224 +++++++++++
.../version-2.7.1/security-tls-keystore.md | 326 +++++++++++++++
.../version-2.7.1/security-tls-transport.md | 292 ++++++++++++++
.../versioned_sidebars/version-2.7.1-sidebars.json | 54 +++
13 files changed, 2743 insertions(+)
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-athenz.md b/site2/website-next/versioned_docs/version-2.7.1/security-athenz.md
new file mode 100644
index 0000000..c4f79cb
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-athenz.md
@@ -0,0 +1,102 @@
+---
+id: security-athenz
+title: Authentication using Athenz
+sidebar_label: "Authentication using Athenz"
+original_id: security-athenz
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+[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 authentication settings
+
+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.
+
+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 do the following 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 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, refer to [Example Service Access Control Setup](https://github.com/AthenZ/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 do the following things:
+
+1. Create a domain, such as `pulsar`
+2. Create a role
+3. Add the tenant service to members of the role
+
+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, 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
+
+> ### TLS encryption
+>
+> 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 encryption see [Architecture - Data Model](https://github.com/AthenZ/athenz/blob/master/docs/data_model)).
+
+In the `conf/broker.conf` configuration file in your Pulsar installation, you need to provide the class name of the Athenz authentication provider as well as a comma-separated list of provider domain names.
+
+```properties
+
+# Add the Athenz auth provider
+authenticationEnabled=true
+authorizationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
+athenzDomainNames=pulsar
+
+# Enable TLS
+tlsEnabled=true
+tlsCertificateFilePath=/path/to/broker-cert.pem
+tlsKeyFilePath=/path/to/broker-key.pem
+
+# Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
+brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
+
+```
+
+> 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
+
+For more information on Pulsar client authentication using Athenz, see the following language-specific docs:
+
+* [Java client](client-libraries-java.md#athenz)
+
+## Configure CLI tools for Athenz
+
+[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](reference-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 authentication parameters to the `conf/client.conf` config file to use Athenz with CLI tools of Pulsar:
+
+```properties
+
+# URL for the broker
+serviceUrl=https://broker.example.com:8443/
+
+# Set Athenz auth plugin and its parameters
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
+authParams={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
+
+# Enable TLS
+useTls=true
+tlsAllowInsecureConnection=false
+tlsTrustCertsFilePath=/path/to/cacert.pem
+
+```
+
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-authorization.md b/site2/website-next/versioned_docs/version-2.7.1/security-authorization.md
new file mode 100644
index 0000000..9ca30ea
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-authorization.md
@@ -0,0 +1,118 @@
+---
+id: security-authorization
+title: Authentication and authorization in Pulsar
+sidebar_label: "Authorization and ACLs"
+original_id: security-authorization
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+
+In Pulsar, the [authentication provider](security-overview.md#authentication-providers) is responsible for properly identifying clients and associating the clients with [role tokens](security-overview.md#role-tokens). If you only enable authentication, an authenticated role token has the ability to access all resources in the cluster. *Authorization* is the process that determines *what* clients are able to do.
+
+The role tokens with the most privileges are the *superusers*. The *superusers* can create and destroy tenants, along with having full access to all tenant resources.
+
+When a superuser creates a [tenant](reference-terminology.md#tenant), that tenant is assigned an admin role. A client with the admin role token can then create, modify and destroy namespaces, and grant and revoke permissions to *other role tokens* on those namespaces.
+
+## Broker and Proxy Setup
+
+### Enable authorization and assign superusers
+You can enable the authorization and assign the superusers in the broker ([`conf/broker.conf`](reference-configuration.md#broker)) configuration files.
+
+```properties
+
+authorizationEnabled=true
+superUserRoles=my-super-user-1,my-super-user-2
+
+```
+
+> A full list 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).
+
+Typically, you use superuser roles for administrators, clients as well as broker-to-broker authorization. When you use [geo-replication](concepts-replication), every broker needs to be able to publish to all the other topics of clusters.
+
+You can also enable the authorization for the proxy in the proxy configuration file (`conf/proxy.conf`). Once you enable the authorization on the proxy, the proxy does an additional authorization check before forwarding the request to a broker.
+If you enable authorization on the broker, the broker checks the authorization of the request when the broker receives the forwarded request.
+
+### Proxy Roles
+
+By default, the broker treats the connection between a proxy and the broker as a normal user connection. The broker authenticates the user as the role configured in `proxy.conf`(see ["Enable TLS Authentication on Proxies"](security-tls-authentication.md#enable-tls-authentication-on-proxies)). However, when the user connects to the cluster through a proxy, the user rarely requires the authentication. The user expects to be able to interact with the cluster as the role for which they have [...]
+
+Pulsar uses *Proxy roles* to enable the authentication. Proxy roles are specified in the broker configuration file, [`conf/broker.conf`](reference-configuration.md#broker). If a client that is authenticated with a broker is one of its ```proxyRoles```, all requests from that client must also carry information about the role of the client that is authenticated with the proxy. This information is called the *original principal*. If the *original principal* is absent, the client is not able [...]
+
+You must authorize both the *proxy role* and the *original principal* to access a resource to ensure that the resource is accessible via the proxy. Administrators can take two approaches to authorize the *proxy role* and the *original principal*.
+
+The more secure approach is to grant access to the proxy roles each time you grant access to a resource. For example, if you have a proxy role named `proxy1`, when the superuser creates a tenant, you should specify `proxy1` as one of the admin roles. When a role is granted permissions to produce or consume from a namespace, if that client wants to produce or consume through a proxy, you should also grant `proxy1` the same permissions.
+
+Another approach is to make the proxy role a superuser. This allows the proxy to access all resources. The client still needs to authenticate with the proxy, and all requests made through the proxy have their role downgraded to the *original principal* of the authenticated client. However, if the proxy is compromised, a bad actor could get full access to your cluster.
+
+You can specify the roles as proxy roles in [`conf/broker.conf`](reference-configuration.md#broker).
+
+```
+
+proxyRoles=my-proxy-role
+
+# if you want to allow superusers to use the proxy (see above)
+superUserRoles=my-super-user-1,my-super-user-2,my-proxy-role
+
+```
+
+## Administer tenants
+
+Pulsar [instance](reference-terminology.md#instance) administrators or some kind of self-service portal typically provisions a Pulsar [tenant](reference-terminology.md#tenant).
+
+You can manage tenants using the [`pulsar-admin`](reference-pulsar-admin) tool.
+
+### Create a new tenant
+
+The following is an example tenant creation command:
+
+```
+
+$ bin/pulsar-admin tenants create my-tenant \
+ --admin-roles my-admin-role \
+ --allowed-clusters us-west,us-east
+
+```
+
+This command creates a new tenant `my-tenant` that is allowed to use the clusters `us-west` and `us-east`.
+
+A client that successfully identifies itself as having the role `my-admin-role` is allowed to perform all administrative tasks on this tenant.
+
+The structure of topic names in Pulsar reflects the hierarchy between tenants, clusters, and namespaces:
+
+```
+
+persistent://tenant/namespace/topic
+
+```
+
+### Manage permissions
+
+You can use [Pulsar Admin Tools](admin-api-permissions) for managing permission in Pulsar.
+
+### Pulsar admin authentication
+
+```
+
+PulsarAdmin admin = PulsarAdmin.builder()
+ .serviceHttpUrl("http://broker:8080")
+ .authentication("com.org.MyAuthPluginClass", "param1:value1")
+ .build();
+
+```
+
+To use TLS:
+
+```
+
+PulsarAdmin admin = PulsarAdmin.builder()
+ .serviceHttpUrl("https://broker:8080")
+ .authentication("com.org.MyAuthPluginClass", "param1:value1")
+ .tlsTrustCertsFilePath("/path/to/trust/cert")
+ .build();
+
+```
+
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-bouncy-castle.md b/site2/website-next/versioned_docs/version-2.7.1/security-bouncy-castle.md
new file mode 100644
index 0000000..b9bb815
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-bouncy-castle.md
@@ -0,0 +1,161 @@
+---
+id: security-bouncy-castle
+title: Bouncy Castle Providers
+sidebar_label: "Bouncy Castle Providers"
+original_id: security-bouncy-castle
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+## BouncyCastle Introduce
+
+`Bouncy Castle` is a Java library that complements the default Java Cryptographic Extension (JCE),
+and it provides more cipher suites and algorithms than the default JCE provided by Sun.
+
+In addition to that, `Bouncy Castle` has lots of utilities for reading arcane formats like PEM and ASN.1 that no sane person would want to rewrite themselves.
+
+In Pulsar, security and crypto have dependencies on BouncyCastle Jars. For the detailed installing and configuring Bouncy Castle FIPS, see [BC FIPS Documentation](https://www.bouncycastle.org/documentation.html), especially the **User Guides** and **Security Policy** PDFs.
+
+`Bouncy Castle` provides both [FIPS](https://www.bouncycastle.org/fips_faq.html) and non-FIPS version. But in a JVM, you can not include both of the 2 versions, and you need to exclude the current version before include the other.
+
+In Pulsar, the security and crypto methods also depends on `Bouncy Castle`, especially in [TLS Authentication](security-tls-authentication.md) and [Transport Encryption](security-encryption). This document contains the configuration between BouncyCastle FIPS(BC-FIPS) and non-FIPS(BC-non-FIPS) version while using Pulsar.
+
+## How BouncyCastle modules packaged in Pulsar
+
+In Pulsar's `bouncy-castle` module, We provide 2 sub modules: `bouncy-castle-bc`(for non-FIPS version) and `bouncy-castle-bcfips`(for FIPS version), to package BC jars together to make the include and exclude of `Bouncy Castle` easier.
+
+To achieve this goal, we will need to package several `bouncy-castle` jars together into `bouncy-castle-bc` or `bouncy-castle-bcfips` jar.
+Each of the original bouncy-castle jar is related with security, so BouncyCastle dutifully supplies signed of each JAR.
+But when we do the re-package, Maven shade explodes the BouncyCastle jar file which puts the signatures into META-INF,
+these signatures aren't valid for this new, uber-jar (signatures are only for the original BC jar).
+Usually, You will meet error like `java.lang.SecurityException: Invalid signature file digest for Manifest main attributes`.
+
+You could exclude these signatures in mvn pom file to avoid above error, by
+
+```access transformers
+
+<exclude>META-INF/*.SF</exclude>
+<exclude>META-INF/*.DSA</exclude>
+<exclude>META-INF/*.RSA</exclude>
+
+```
+
+But it can also lead to new, cryptic errors, e.g. `java.security.NoSuchAlgorithmException: PBEWithSHA256And256BitAES-CBC-BC SecretKeyFactory not available`
+By explicitly specifying where to find the algorithm like this: `SecretKeyFactory.getInstance("PBEWithSHA256And256BitAES-CBC-BC","BC")`
+It will get the real error: `java.security.NoSuchProviderException: JCE cannot authenticate the provider BC`
+
+So, we used a [executable packer plugin](https://github.com/nthuemmel/executable-packer-maven-plugin) that uses a jar-in-jar approach to preserve the BouncyCastle signature in a single, executable jar.
+
+### Include dependencies of BC-non-FIPS
+
+Pulsar module `bouncy-castle-bc`, which defined by `bouncy-castle/bc/pom.xml` contains the needed non-FIPS jars for Pulsar, and packaged as a jar-in-jar(need to provide `<classifier>pkg</classifier>`).
+
+```xml
+
+ <dependency>
+ <groupId>org.bouncycastle</groupId>
+ <artifactId>bcpkix-jdk15on</artifactId>
+ <version>${bouncycastle.version}</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.bouncycastle</groupId>
+ <artifactId>bcprov-ext-jdk15on</artifactId>
+ <version>${bouncycastle.version}</version>
+ </dependency>
+
+```
+
+By using this `bouncy-castle-bc` module, you can easily include and exclude BouncyCastle non-FIPS jars.
+
+### Modules that include BC-non-FIPS module (`bouncy-castle-bc`)
+
+For Pulsar client, user need the bouncy-castle module, so `pulsar-client-original` will include the `bouncy-castle-bc` module, and have `<classifier>pkg</classifier>` set to reference the `jar-in-jar` package.
+It is included as following example:
+
+```xml
+
+ <dependency>
+ <groupId>org.apache.pulsar</groupId>
+ <artifactId>bouncy-castle-bc</artifactId>
+ <version>${pulsar.version}</version>
+ <classifier>pkg</classifier>
+ </dependency>
+
+```
+
+By default `bouncy-castle-bc` already included in `pulsar-client-original`, And `pulsar-client-original` has been included in a lot of other modules like `pulsar-client-admin`, `pulsar-broker`.
+But for the above shaded jar and signatures reason, we should not package Pulsar's `bouncy-castle` module into `pulsar-client-all` other shaded modules directly, such as `pulsar-client-shaded`, `pulsar-client-admin-shaded` and `pulsar-broker-shaded`.
+So in the shaded modules, we will exclude the `bouncy-castle` modules.
+
+```xml
+
+ <filters>
+ <filter>
+ <artifact>org.apache.pulsar:pulsar-client-original</artifact>
+ <includes>
+ <include>**</include>
+ </includes>
+ <excludes>
+ <exclude>org/bouncycastle/**</exclude>
+ </excludes>
+ </filter>
+ </filters>
+
+```
+
+That means, `bouncy-castle` related jars are not shaded in these fat jars.
+
+### Module BC-FIPS (`bouncy-castle-bcfips`)
+
+Pulsar module `bouncy-castle-bcfips`, which defined by `bouncy-castle/bcfips/pom.xml` contains the needed FIPS jars for Pulsar.
+Similar to `bouncy-castle-bc`, `bouncy-castle-bcfips` also packaged as a `jar-in-jar` package for easy include/exclude.
+
+```xml
+
+ <dependency>
+ <groupId>org.bouncycastle</groupId>
+ <artifactId>bc-fips</artifactId>
+ <version>${bouncycastlefips.version}</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.bouncycastle</groupId>
+ <artifactId>bcpkix-fips</artifactId>
+ <version>${bouncycastlefips.version}</version>
+ </dependency>
+
+```
+
+### Exclude BC-non-FIPS and include BC-FIPS
+
+If you want to switch from BC-non-FIPS to BC-FIPS version, Here is an example for `pulsar-broker` module:
+
+```xml
+
+ <dependency>
+ <groupId>org.apache.pulsar</groupId>
+ <artifactId>pulsar-broker</artifactId>
+ <version>${pulsar.version}</version>
+ <exclusions>
+ <exclusion>
+ <groupId>org.apache.pulsar</groupId>
+ <artifactId>bouncy-castle-bc</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.pulsar</groupId>
+ <artifactId>bouncy-castle-bcfips</artifactId>
+ <version>${pulsar.version}</version>
+ <classifier>pkg</classifier>
+ </dependency>
+
+```
+
+
+For more example, you can reference module `bcfips-include-test`.
+
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-encryption.md b/site2/website-next/versioned_docs/version-2.7.1/security-encryption.md
new file mode 100644
index 0000000..b0f2f46
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-encryption.md
@@ -0,0 +1,194 @@
+---
+id: security-encryption
+title: Pulsar Encryption
+sidebar_label: "End-to-End Encryption"
+original_id: security-encryption
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+Applications can use Pulsar encryption to encrypt messages at the producer side and decrypt messages at the consumer side. You can use the public and private key pair that the application configures to perform encryption. Only the consumers with a valid key can decrypt the encrypted messages.
+
+## Asymmetric and symmetric encryption
+
+Pulsar uses dynamically generated symmetric AES key to encrypt messages(data). You can use the application provided ECDSA/RSA key pair to encrypt the AES key(data key), so you do not have to share the secret with everyone.
+
+Key is a public and private key pair used for encryption or decryption. The producer key is the public key of the key pair, and the consumer key is the private key of the key pair.
+
+The application configures the producer with the public key. You can use this key to encrypt the AES data key. The encrypted data key is sent as part of message header. Only entities with the private key (in this case the consumer) are able to decrypt the data key which is used to decrypt the message.
+
+You can encrypt a message with more than one key. Any one of the keys used for encrypting the message is sufficient to decrypt the message.
+
+Pulsar does not store the encryption key anywhere in the Pulsar service. If you lose or delete the private key, your message is irretrievably lost, and is unrecoverable.
+
+## Producer
+
+
+## Consumer
+
+
+## Get started
+
+1. Enter the commands below to create your ECDSA or RSA public and private key pair.
+
+```shell
+
+openssl ecparam -name secp521r1 -genkey -param_enc explicit -out test_ecdsa_privkey.pem
+openssl ec -in test_ecdsa_privkey.pem -pubout -outform pem -out test_ecdsa_pubkey.pem
+
+```
+
+2. Add the public and private key to the key management and configure your producers to retrieve public keys and consumers clients to retrieve private keys.
+
+3. Implement the CryptoKeyReader interface, specifically CryptoKeyReader.getPublicKey() for producer and CryptoKeyReader.getPrivateKey() for consumer, which Pulsar client invokes to load the key.
+
+4. Add encryption key name to producer builder: PulsarClient.newProducer().addEncryptionKey("myapp.key").
+
+5. Add CryptoKeyReader implementation to producer or consumer builder: PulsarClient.newProducer().cryptoKeyReader(keyReader) / PulsarClient.newConsumer().cryptoKeyReader(keyReader).
+
+6. Sample producer application:
+
+```java
+
+class RawFileKeyReader implements CryptoKeyReader {
+
+ String publicKeyFile = "";
+ String privateKeyFile = "";
+
+ RawFileKeyReader(String pubKeyFile, String privKeyFile) {
+ publicKeyFile = pubKeyFile;
+ privateKeyFile = privKeyFile;
+ }
+
+ @Override
+ public EncryptionKeyInfo getPublicKey(String keyName, Map<String, String> keyMeta) {
+ EncryptionKeyInfo keyInfo = new EncryptionKeyInfo();
+ try {
+ keyInfo.setKey(Files.readAllBytes(Paths.get(publicKeyFile)));
+ } catch (IOException e) {
+ System.out.println("ERROR: Failed to read public key from file " + publicKeyFile);
+ e.printStackTrace();
+ }
+ return keyInfo;
+ }
+
+ @Override
+ public EncryptionKeyInfo getPrivateKey(String keyName, Map<String, String> keyMeta) {
+ EncryptionKeyInfo keyInfo = new EncryptionKeyInfo();
+ try {
+ keyInfo.setKey(Files.readAllBytes(Paths.get(privateKeyFile)));
+ } catch (IOException e) {
+ System.out.println("ERROR: Failed to read private key from file " + privateKeyFile);
+ e.printStackTrace();
+ }
+ return keyInfo;
+ }
+}
+
+PulsarClient pulsarClient = PulsarClient.builder().serviceUrl("pulsar://localhost:6650").build();
+
+Producer producer = pulsarClient.newProducer()
+ .topic("persistent://my-tenant/my-ns/my-topic")
+ .addEncryptionKey("myappkey")
+ .cryptoKeyReader(new RawFileKeyReader("test_ecdsa_pubkey.pem", "test_ecdsa_privkey.pem"))
+ .create();
+
+for (int i = 0; i < 10; i++) {
+ producer.send("my-message".getBytes());
+}
+
+producer.close();
+pulsarClient.close();
+
+```
+
+7. Sample Consumer Application:
+
+```java
+
+class RawFileKeyReader implements CryptoKeyReader {
+
+ String publicKeyFile = "";
+ String privateKeyFile = "";
+
+ RawFileKeyReader(String pubKeyFile, String privKeyFile) {
+ publicKeyFile = pubKeyFile;
+ privateKeyFile = privKeyFile;
+ }
+
+ @Override
+ public EncryptionKeyInfo getPublicKey(String keyName, Map<String, String> keyMeta) {
+ EncryptionKeyInfo keyInfo = new EncryptionKeyInfo();
+ try {
+ keyInfo.setKey(Files.readAllBytes(Paths.get(publicKeyFile)));
+ } catch (IOException e) {
+ System.out.println("ERROR: Failed to read public key from file " + publicKeyFile);
+ e.printStackTrace();
+ }
+ return keyInfo;
+ }
+
+ @Override
+ public EncryptionKeyInfo getPrivateKey(String keyName, Map<String, String> keyMeta) {
+ EncryptionKeyInfo keyInfo = new EncryptionKeyInfo();
+ try {
+ keyInfo.setKey(Files.readAllBytes(Paths.get(privateKeyFile)));
+ } catch (IOException e) {
+ System.out.println("ERROR: Failed to read private key from file " + privateKeyFile);
+ e.printStackTrace();
+ }
+ return keyInfo;
+ }
+}
+
+PulsarClient pulsarClient = PulsarClient.builder().serviceUrl("pulsar://localhost:6650").build();
+Consumer consumer = pulsarClient.newConsumer()
+ .topic("persistent://my-tenant/my-ns/my-topic")
+ .subscriptionName("my-subscriber-name")
+ .cryptoKeyReader(new RawFileKeyReader("test_ecdsa_pubkey.pem", "test_ecdsa_privkey.pem"))
+ .subscribe();
+Message msg = null;
+
+for (int i = 0; i < 10; i++) {
+ msg = consumer.receive();
+ // do something
+ System.out.println("Received: " + new String(msg.getData()));
+}
+
+// Acknowledge the consumption of all messages at once
+consumer.acknowledgeCumulative(msg);
+consumer.close();
+pulsarClient.close();
+
+```
+
+## Key rotation
+Pulsar generates a new AES data key every 4 hours or after publishing a certain number of messages. A producer fetches the asymmetric public key every 4 hours by calling CryptoKeyReader.getPublicKey() to retrieve the latest version.
+
+## Enable encryption at the producer application
+If you produce messages that are consumed across application boundaries, you need to ensure that consumers in other applications have access to one of the private keys that can decrypt the messages. You can do this in two ways:
+1. The consumer application provides you access to their public key, which you add to your producer keys.
+2. You grant access to one of the private keys from the pairs that producer uses.
+
+When producers want to encrypt the messages with multiple keys, producers add all such keys to the config. Consumer can decrypt the message as long as the consumer has access to at least one of the keys.
+
+If you need to encrypt the messages using 2 keys (myapp.messagekey1 and myapp.messagekey2), refer to the following example.
+
+```java
+
+PulsarClient.newProducer().addEncryptionKey("myapp.messagekey1").addEncryptionKey("myapp.messagekey2");
+
+```
+
+## Decrypt encrypted messages at the consumer application
+Consumers require access one of the private keys to decrypt messages that the producer produces. If you want to receive encrypted messages, create a public or private key and give your public key to the producer application to encrypt messages using your public key.
+
+## Handle failures
+* Producer/ Consumer loses access to the key
+ * Producer action fails indicating the cause of the failure. Application has the option to proceed with sending unencrypted message in such cases. Call PulsarClient.newProducer().cryptoFailureAction(ProducerCryptoFailureAction) to control the producer behavior. The default behavior is to fail the request.
+ * If consumption fails due to decryption failure or missing keys in consumer, application has the option to consume the encrypted message or discard it. Call PulsarClient.newConsumer().cryptoFailureAction(ConsumerCryptoFailureAction) to control the consumer behavior. The default behavior is to fail the request. Application is never able to decrypt the messages if the private key is permanently lost.
+* Batch messaging
+ * If decryption fails and the message contains batch messages, client is not able to retrieve individual messages in the batch, hence message consumption fails even if cryptoFailureAction() is set to ConsumerCryptoFailureAction.CONSUME.
+* If decryption fails, the message consumption stops and application notices backlog growth in addition to decryption failure messages in the client log. If application does not have access to the private key to decrypt the message, the only option is to skip or discard backlogged messages.
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-extending.md b/site2/website-next/versioned_docs/version-2.7.1/security-extending.md
new file mode 100644
index 0000000..57128da
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-extending.md
@@ -0,0 +1,211 @@
+---
+id: security-extending
+title: Extending Authentication and Authorization in Pulsar
+sidebar_label: "Extending"
+original_id: security-extending
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+Pulsar provides a way to use custom authentication and authorization mechanisms.
+
+## Authentication
+
+Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
+
+You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+
+### Client authentication plugin
+
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+
+```java
+
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://localhost:6650")
+ .authentication(new MyAuthentication())
+ .build();
+
+```
+
+You can use 2 interfaces to implement on the client side:
+ * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
+ * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
+
+
+This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
+
+
+You can find examples for client authentication providers at:
+
+ * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
+ * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+
+### Proxy/Broker authentication plugin
+
+On the proxy/broker side, you need to configure the corresponding plugin to validate the credentials that the client sends. The Proxy and Broker can support multiple authentication providers at the same time.
+
+In `conf/broker.conf` you can choose to specify a list of valid providers:
+
+```properties
+
+# Authentication provider name list, which is comma separated list of class names
+authenticationProviders=
+
+```
+
+To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+
+```java
+
+/**
+ * Provider of authentication mechanism
+ */
+public interface AuthenticationProvider extends Closeable {
+
+ /**
+ * Perform initialization for the authentication provider
+ *
+ * @param config
+ * broker config object
+ * @throws IOException
+ * if the initialization fails
+ */
+ void initialize(ServiceConfiguration config) throws IOException;
+
+ /**
+ * @return the authentication method name supported by this provider
+ */
+ String getAuthMethodName();
+
+ /**
+ * Validate the authentication for the given credentials with the specified authentication data
+ *
+ * @param authData
+ * provider specific authentication data
+ * @return the "role" string for the authenticated connection, if the authentication was successful
+ * @throws AuthenticationException
+ * if the credentials are not valid
+ */
+ String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
+
+}
+
+```
+
+The following is the example for Broker authentication plugins:
+
+ * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
+ * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+
+## Authorization
+
+Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
+
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
+Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
+the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+
+To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+
+ ```properties
+
+ # Authorization provider fully qualified class-name
+ authorizationProvider=org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
+
+ ```
+
+```java
+
+/**
+ * Provider of authorization mechanism
+ */
+public interface AuthorizationProvider extends Closeable {
+
+ /**
+ * Perform initialization for the authorization provider
+ *
+ * @param conf
+ * broker config object
+ * @param configCache
+ * pulsar zk configuration cache service
+ * @throws IOException
+ * if the initialization fails
+ */
+ void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
+
+ /**
+ * Check if the specified role has permission to send messages to the specified fully qualified topic name.
+ *
+ * @param topicName
+ * the fully qualified topic name associated with the topic.
+ * @param role
+ * the app id used to send messages to the topic.
+ */
+ CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
+ AuthenticationDataSource authenticationData);
+
+ /**
+ * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
+ *
+ * @param topicName
+ * the fully qualified topic name associated with the topic.
+ * @param role
+ * the app id used to receive messages from the topic.
+ * @param subscription
+ * the subscription name defined by the client
+ */
+ CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
+ AuthenticationDataSource authenticationData, String subscription);
+
+ /**
+ * Check whether the specified role can perform a lookup for the specified topic.
+ *
+ * For that the caller needs to have producer or consumer permission.
+ *
+ * @param topicName
+ * @param role
+ * @return
+ * @throws Exception
+ */
+ CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
+ AuthenticationDataSource authenticationData);
+
+ /**
+ *
+ * Grant authorization-action permission on a namespace to the given client
+ *
+ * @param namespace
+ * @param actions
+ * @param role
+ * @param authDataJson
+ * additional authdata in json format
+ * @return CompletableFuture
+ * @completesWith <br />
+ * IllegalArgumentException when namespace not found<br />
+ * IllegalStateException when failed to grant permission
+ */
+ CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
+ String authDataJson);
+
+ /**
+ * Grant authorization-action permission on a topic to the given client
+ *
+ * @param topicName
+ * @param role
+ * @param authDataJson
+ * additional authdata in json format
+ * @return CompletableFuture
+ * @completesWith <br />
+ * IllegalArgumentException when namespace not found<br />
+ * IllegalStateException when failed to grant permission
+ */
+ CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
+ String authDataJson);
+
+}
+
+```
+
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-jwt.md b/site2/website-next/versioned_docs/version-2.7.1/security-jwt.md
new file mode 100644
index 0000000..006c664
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-jwt.md
@@ -0,0 +1,344 @@
+---
+id: security-jwt
+title: Client authentication using tokens based on JSON Web Tokens
+sidebar_label: "Authentication using JWT"
+original_id: security-jwt
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+## 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 token string from the administrator (or some automated service).
+
+The compact representation of a signed JWT is a string that looks like as the following:
+
+```
+
+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 connect to the Pulsar service. See
+> [Transport Encryption using TLS](security-tls-transport) for more details.
+
+### CLI Tools
+
+[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](reference-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:
+
+```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
+
+```
+
+### Pulsar client
+
+You can use tokens to authenticate the following Pulsar clients.
+
+<Tabs
+ 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 {
+ // Read token from custom source
+ return readToken()
+ }),
+})
+
+```
+
+</TabItem>
+<TabItem value="C++">
+
+```c++
+
+#include <pulsar/Client.h>
+
+pulsar::ClientConfiguration config;
+config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"));
+
+pulsar::Client client("pulsar://broker.example.com:6650/", config);
+
+```
+
+</TabItem>
+<TabItem value="C#">
+
+```c#
+
+var client = PulsarClient.Builder()
+ .AuthenticateUsingToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")
+ .Build();
+
+```
+
+</TabItem>
+
+</Tabs>
+
+## Enable token authentication
+
+On how to enable token authentication on a Pulsar cluster, you can refer to the guide below.
+
+JWT supports two different kinds of keys in order to generate and validate the tokens:
+
+ * Symmetric :
+ - You can use a single ***Secret*** key to generate and validate tokens.
+ * Asymmetric: A pair of keys consists 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 secret key
+
+When you use a secret key, the administrator creates the key and uses the key to generate the client tokens. You can also configure this key to brokers in order to validate the clients.
+
+Output file is generated in the root of your Pulsar installation directory. You can also provide absolute path for the output file using the command below.
+
+```shell
+
+$ bin/pulsar tokens create-secret-key --output my-secret.key
+
+```
+
+Enter this command to generate base64 encoded private key.
+
+```shell
+
+$ bin/pulsar tokens create-secret-key --output /opt/my-secret.key --base64
+
+```
+
+### Create a key pair
+
+With Public and Private keys, you need to create a pair of keys. Pulsar supports all algorithms that the Java JWT library (shown [here](https://github.com/jwtk/jjwt#signature-algorithms-keys)) supports.
+
+Output file is generated in the root of your Pulsar installation directory. You can also provide absolute path for the output file using the command below.
+
+```shell
+
+$ bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
+
+```
+
+ * Store `my-private.key` in a safe location and only administrator can use `my-private.key` to generate new tokens.
+ * `my-public.key` is distributed to all Pulsar brokers. You can publicly share this file without any security concern.
+
+### Generate tokens
+
+A token is the credential associated with a user. The association is done through the "principal" or "role". In the case of JWT tokens, this field is typically referred as **subject**, though they are exactly the same concept.
+
+Then, you need to use this command to require the generated token to have a **subject** field set.
+
+```shell
+
+$ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
+ --subject test-user
+
+```
+
+This command prints the token string on stdout.
+
+Similarly, you can create a token by passing the "private" key using the command below:
+
+```shell
+
+$ bin/pulsar tokens create --private-key file:///path/to/my-private.key \
+ --subject test-user
+
+```
+
+Finally, you can enter the following command to create a token with a pre-defined TTL. And then the token is automatically invalidated.
+
+```shell
+
+$ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
+ --subject test-user \
+ --expiry-time 1y
+
+```
+
+### Authorization
+
+The token itself does not have any permission associated. The authorization engine determines whether the token should have permissions or not. Once you have created the token, you can grant permission for this token to do certain actions. The following is an example.
+
+```shell
+
+$ bin/pulsar-admin namespaces grant-permission my-tenant/my-namespace \
+ --role test-user \
+ --actions produce,consume
+
+```
+
+### Enable token authentication on Brokers
+
+To configure brokers to authenticate clients, add the following parameters to `broker.conf`:
+
+```properties
+
+# Configuration to enable authentication and authorization
+authenticationEnabled=true
+authorizationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
+
+# Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters
+brokerClientTlsEnabled=true
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw"}
+# Or, alternatively, read token from file
+# brokerClientAuthenticationParameters={"file":"///path/to/proxy-token.txt"}
+brokerClientTrustCertsFilePath=/path/my-ca/certs/ca.cert.pem
+
+# If this flag is set then the broker authenticates the original Auth data
+# else it just accepts the originalPrincipal and authorizes it (if required).
+authenticateOriginalAuthData=true
+
+# If using secret key
+tokenSecretKey=file:///path/to/secret.key
+# The key can also be passed inline:
+# tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU=
+
+# If using public/private
+# tokenPublicKey=file:///path/to/public.key
+
+```
+
+### Enable token authentication on Proxies
+
+To configure proxies to authenticate clients, add the following parameters to `proxy.conf`:
+
+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 the [authorization guide](security-authorization).
+
+```properties
+
+# For clients connecting to the proxy
+authenticationEnabled=true
+authorizationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
+tokenSecretKey=file:///path/to/secret.key
+
+# For the proxy to connect to brokers
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
+brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw"}
+# Or, alternatively, read token from file
+# brokerClientAuthenticationParameters={"file":"///path/to/proxy-token.txt"}
+
+# Whether client authorization credentials are forwarded to the broker for re-authorization.
+# Authentication must be enabled via authenticationEnabled=true for this to take effect.
+forwardAuthorizationCredentials=true
+
+```
+
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-kerberos.md b/site2/website-next/versioned_docs/version-2.7.1/security-kerberos.md
new file mode 100644
index 0000000..32e12f1
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-kerberos.md
@@ -0,0 +1,447 @@
+---
+id: security-kerberos
+title: Authentication using Kerberos
+sidebar_label: "Authentication using Kerberos"
+original_id: security-kerberos
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+[Kerberos](https://web.mit.edu/kerberos/) is a network authentication protocol. By using secret-key cryptography, [Kerberos](https://web.mit.edu/kerberos/) is designed to provide strong authentication for client applications and server applications.
+
+In Pulsar, you can use Kerberos with [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) as a choice for authentication. And Pulsar uses the [Java Authentication and Authorization Service (JAAS)](https://en.wikipedia.org/wiki/Java_Authentication_and_Authorization_Service) for SASL configuration. You need to provide JAAS configurations for Kerberos authentication.
+
+This document introduces how to configure `Kerberos` with `SASL` between Pulsar clients and brokers and how to configure Kerberos for Pulsar proxy in detail.
+
+## Configuration for Kerberos between Client and Broker
+
+### Prerequisites
+
+To begin, you need to set up (or already have) a [Key Distribution Center(KDC)](https://en.wikipedia.org/wiki/Key_distribution_center). Also you need to configure and run the [Key Distribution Center(KDC)](https://en.wikipedia.org/wiki/Key_distribution_center)in advance.
+
+If your organization already uses a Kerberos server (for example, by using `Active Directory`), you do not have to install a new server for Pulsar. If your organization does not use a Kerberos server, you need to install one. Your Linux vendor might have packages for `Kerberos`. On how to install and configure Kerberos, refer to [Ubuntu](https://help.ubuntu.com/community/Kerberos),
+[Redhat](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/installing-kerberos.html).
+
+Note that if you use Oracle Java, you need to download JCE policy files for your Java version and copy them to the `$JAVA_HOME/jre/lib/security` directory.
+
+#### Kerberos principals
+
+If you use the existing Kerberos system, ask your Kerberos administrator for a principal for each Brokers in your cluster and for every operating system user that accesses Pulsar with Kerberos authentication(via clients and tools).
+
+If you have installed your own Kerberos system, you can create these principals with the following commands:
+
+```shell
+
+### add Principals for broker
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey broker/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{broker-keytabname}.keytab broker/{hostname}@{REALM}"
+### add Principals for client
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey client/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{client-keytabname}.keytab client/{hostname}@{REALM}"
+
+```
+
+Note that *Kerberos* requires that all your hosts can be resolved with their FQDNs.
+
+The first part of Broker principal (for example, `broker` in `broker/{hostname}@{REALM}`) is the `serverType` of each host. The suggested values of `serverType` are `broker` (host machine runs service Pulsar Broker) and `proxy` (host machine runs service Pulsar Proxy).
+
+#### Configure how to connect to KDC
+
+You need to enter the command below to specify the path to the `krb5.conf` file for the client side and the broker side. The content of `krb5.conf` file indicates the default Realm and KDC information. See [JDK’s Kerberos Requirements](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html) for more details.
+
+```shell
+
+-Djava.security.krb5.conf=/etc/pulsar/krb5.conf
+
+```
+
+Here is an example of the krb5.conf file:
+
+In the configuration file, `EXAMPLE.COM` is the default realm; `kdc = localhost:62037` is the kdc server url for realm `EXAMPLE.COM `:
+
+```
+
+[libdefaults]
+ default_realm = EXAMPLE.COM
+
+[realms]
+ EXAMPLE.COM = {
+ kdc = localhost:62037
+ }
+
+```
+
+Usually machines configured with kerberos already have a system wide configuration and this configuration is optional.
+
+#### JAAS configuration file
+
+You need JAAS configuration file for the client side and the broker side. JAAS configuration file provides the section of information that is used to connect KDC. Here is an example named `pulsar_jaas.conf`:
+
+```
+
+ PulsarBroker {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarbroker.keytab"
+ principal="broker/localhost@EXAMPLE.COM";
+};
+
+ PulsarClient {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarclient.keytab"
+ principal="client/localhost@EXAMPLE.COM";
+};
+
+```
+
+You need to set the `JAAS` configuration file path as JVM parameter for client and broker. For example:
+
+```shell
+
+ -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf
+
+```
+
+In the `pulsar_jaas.conf` file above
+
+1. `PulsarBroker` is a section name in the JAAS file that each broker uses. This section tells the broker to use which principal inside Kerberos and the location of the keytab where the principal is stored. `PulsarBroker` allows the broker to use the keytab specified in this section.
+2. `PulsarClient` is a section name in the JASS file that each broker uses. This section tells the client to use which principal inside Kerberos and the location of the keytab where the principal is stored. `PulsarClient` allows the client to use the keytab specified in this section.
+ The following example also reuses this `PulsarClient` section in both the Pulsar internal admin configuration and in CLI command of `bin/pulsar-client`, `bin/pulsar-perf` and `bin/pulsar-admin`. You can also add different sections for different use cases.
+
+You can have 2 separate JAAS configuration files:
+* the file for a broker that has sections of both `PulsarBroker` and `PulsarClient`;
+* the file for a client that only has a `PulsarClient` section.
+
+
+### Kerberos configuration for Brokers
+
+#### Configure the `broker.conf` file
+
+ In the `broker.conf` file, set Kerberos related configurations.
+
+ - Set `authenticationEnabled` to `true`;
+ - Set `authenticationProviders` to choose `AuthenticationProviderSasl`;
+ - Set `saslJaasClientAllowedIds` regex for principal that is allowed to connect to broker;
+ - Set `saslJaasBrokerSectionName` that corresponds to the section in JAAS configuration file for broker;
+
+ To make Pulsar internal admin client work properly, you need to set the configuration in the `broker.conf` file as below:
+ - Set `brokerClientAuthenticationPlugin` to client plugin `AuthenticationSasl`;
+ - Set `brokerClientAuthenticationParameters` to value in JSON string `{"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}`, in which `PulsarClient` is the section name in the `pulsar_jaas.conf` file, and `"serverType":"broker"` indicates that the internal admin client connects to a Pulsar Broker;
+
+ Here is an example:
+
+```
+
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
+saslJaasClientAllowedIds=.*client.*
+saslJaasBrokerSectionName=PulsarBroker
+
+## Authentication settings of the broker itself. Used when the broker connects to other brokers
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
+brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
+
+```
+
+#### Set Broker JVM parameter
+
+ Set JVM parameters for JAAS configuration file and krb5 configuration file with additional options.
+
+```shell
+
+ -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf
+
+```
+
+You can add this at the end of `PULSAR_EXTRA_OPTS` in the file [`pulsar_env.sh`](https://github.com/apache/pulsar/blob/master/conf/pulsar_env.sh)
+
+You must ensure that the operating system user who starts broker can reach the keytabs configured in the `pulsar_jaas.conf` file and kdc server in the `krb5.conf` file.
+
+### Kerberos configuration for clients
+
+#### Java Client and Java Admin Client
+
+In client application, include `pulsar-client-auth-sasl` in your project dependency.
+
+```
+
+ <dependency>
+ <groupId>org.apache.pulsar</groupId>
+ <artifactId>pulsar-client-auth-sasl</artifactId>
+ <version>${pulsar.version}</version>
+ </dependency>
+
+```
+
+Configure the authentication type to use `AuthenticationSasl`, and also provide the authentication parameters to it.
+
+You need 2 parameters:
+- `saslJaasClientSectionName`. This parameter corresponds to the section in JAAS configuration file for client;
+- `serverType`. This parameter stands for whether this client connects to broker or proxy. And client uses this parameter to know which server side principal should be used.
+
+When you authenticate between client and broker with the setting in above JAAS configuration file, we need to set `saslJaasClientSectionName` to `PulsarClient` and set `serverType` to `broker`.
+
+The following is an example of creating a Java client:
+
+ ```java
+
+ System.setProperty("java.security.auth.login.config", "/etc/pulsar/pulsar_jaas.conf");
+ System.setProperty("java.security.krb5.conf", "/etc/pulsar/krb5.conf");
+
+ Map<String, String> authParams = Maps.newHashMap();
+ authParams.put("saslJaasClientSectionName", "PulsarClient");
+ authParams.put("serverType", "broker");
+
+ Authentication saslAuth = AuthenticationFactory
+ .create(org.apache.pulsar.client.impl.auth.AuthenticationSasl.class.getName(), authParams);
+
+ PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://my-broker.com:6650")
+ .authentication(saslAuth)
+ .build();
+
+ ```
+
+> The first two lines in the example above are hard coded, alternatively, you can set additional JVM parameters for JAAS and krb5 configuration file when you run the application like below:
+
+```
+
+java -cp -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf $APP-jar-with-dependencies.jar $CLASSNAME
+
+```
+
+You must ensure that the operating system user who starts pulsar client can reach the keytabs configured in the `pulsar_jaas.conf` file and kdc server in the `krb5.conf` file.
+
+#### Configure CLI tools
+
+If you use a command-line tool (such as `bin/pulsar-client`, `bin/pulsar-perf` and `bin/pulsar-admin`), you need to perform the following steps:
+
+Step 1. Enter the command below to configure your `client.conf`.
+
+```shell
+
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
+authParams={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
+
+```
+
+Step 2. Enter the command below to set JVM parameters for JAAS configuration file and krb5 configuration file with additional options.
+
+```shell
+
+ -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf
+
+```
+
+You can add this at the end of `PULSAR_EXTRA_OPTS` in the file [`pulsar_tools_env.sh`](https://github.com/apache/pulsar/blob/master/conf/pulsar_tools_env.sh),
+or add this line `OPTS="$OPTS -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf "` directly to the CLI tool script.
+
+The meaning of configurations is the same as the meaning of configurations in Java client section.
+
+## Kerberos configuration for working with Pulsar Proxy
+
+With the above configuration, client and broker can do authentication using Kerberos.
+
+A client that connects to Pulsar Proxy is a little different. Pulsar Proxy (as a SASL Server in Kerberos) authenticates Client (as a SASL client in Kerberos) first; and then Pulsar broker authenticates Pulsar Proxy.
+
+Now in comparison with the above configuration between client and broker, we show you how to configure Pulsar Proxy as follows.
+
+### Create principal for Pulsar Proxy in Kerberos
+
+You need to add new principals for Pulsar Proxy comparing with the above configuration. If you already have principals for client and broker, you only need to add the proxy principal here.
+
+```shell
+
+### add Principals for Pulsar Proxy
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey proxy/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{proxy-keytabname}.keytab proxy/{hostname}@{REALM}"
+### add Principals for broker
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey broker/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{broker-keytabname}.keytab broker/{hostname}@{REALM}"
+### add Principals for client
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey client/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{client-keytabname}.keytab client/{hostname}@{REALM}"
+
+```
+
+### Add a section in JAAS configuration file for Pulsar Proxy
+
+In comparison with the above configuration, add a new section for Pulsar Proxy in JAAS configuration file.
+
+Here is an example named `pulsar_jaas.conf`:
+
+```
+
+ PulsarBroker {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarbroker.keytab"
+ principal="broker/localhost@EXAMPLE.COM";
+};
+
+ PulsarProxy {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarproxy.keytab"
+ principal="proxy/localhost@EXAMPLE.COM";
+};
+
+ PulsarClient {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarclient.keytab"
+ principal="client/localhost@EXAMPLE.COM";
+};
+
+```
+
+### Proxy client configuration
+
+Pulsar client configuration is similar with client and broker configuration, except that you need to set `serverType` to `proxy` instead of `broker`, for the reason that you need to do the Kerberos authentication between client and proxy.
+
+ ```java
+
+ System.setProperty("java.security.auth.login.config", "/etc/pulsar/pulsar_jaas.conf");
+ System.setProperty("java.security.krb5.conf", "/etc/pulsar/krb5.conf");
+
+ Map<String, String> authParams = Maps.newHashMap();
+ authParams.put("saslJaasClientSectionName", "PulsarClient");
+ authParams.put("serverType", "proxy"); // ** here is the different **
+
+ Authentication saslAuth = AuthenticationFactory
+ .create(org.apache.pulsar.client.impl.auth.AuthenticationSasl.class.getName(), authParams);
+
+ PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://my-broker.com:6650")
+ .authentication(saslAuth)
+ .build();
+
+ ```
+
+> The first two lines in the example above are hard coded, alternatively, you can set additional JVM parameters for JAAS and krb5 configuration file when you run the application like below:
+
+```
+
+java -cp -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf $APP-jar-with-dependencies.jar $CLASSNAME
+
+```
+
+### Kerberos configuration for Pulsar proxy service
+
+In the `proxy.conf` file, set Kerberos related configuration. Here is an example:
+
+```shell
+
+## related to authenticate client.
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
+saslJaasClientAllowedIds=.*client.*
+saslJaasBrokerSectionName=PulsarProxy
+
+## related to be authenticated by broker
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
+brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarProxy", "serverType":"broker"}
+forwardAuthorizationCredentials=true
+
+```
+
+The first part relates to authenticating between client and Pulsar Proxy. In this phase, client works as SASL client, while Pulsar Proxy works as SASL server.
+
+The second part relates to authenticating between Pulsar Proxy and Pulsar Broker. In this phase, Pulsar Proxy works as SASL client, while Pulsar Broker works as SASL server.
+
+### Broker side configuration.
+
+The broker side configuration file is the same with the above `broker.conf`, you do not need special configuration for Pulsar Proxy.
+
+```
+
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
+saslJaasClientAllowedIds=.*client.*
+saslJaasBrokerSectionName=PulsarBroker
+
+```
+
+## Regarding authorization and role token
+
+For Kerberos authentication, we usually use the authenticated principal as the role token for Pulsar authorization. For more information of authorization in Pulsar, see [security authorization](security-authorization).
+
+If you enable 'authorizationEnabled', you need to set `superUserRoles` in `broker.conf` that corresponds to the name registered in kdc.
+
+For example:
+
+```bash
+
+superUserRoles=client/{clientIp}@EXAMPLE.COM
+
+```
+
+## Regarding authentication between ZooKeeper and Broker
+
+Pulsar Broker acts as a Kerberos client when you authenticate with Zookeeper. According to [ZooKeeper document](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Client-Server+mutual+authentication), you need these settings in `conf/zookeeper.conf`:
+
+```
+
+authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
+requireClientAuthScheme=sasl
+
+```
+
+Enter the following commands to add a section of `Client` configurations in the file `pulsar_jaas.conf`, which Pulsar Broker uses:
+
+```
+
+ Client {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarbroker.keytab"
+ principal="broker/localhost@EXAMPLE.COM";
+};
+
+```
+
+In this setting, the principal of Pulsar Broker and keyTab file indicates the role of Broker when you authenticate with ZooKeeper.
+
+## Regarding authentication between BookKeeper and Broker
+
+Pulsar Broker acts as a Kerberos client when you authenticate with Bookie. According to [BookKeeper document](http://bookkeeper.apache.org/docs/latest/security/sasl/), you need to add `bookkeeperClientAuthenticationPlugin` parameter in `broker.conf`:
+
+```
+
+bookkeeperClientAuthenticationPlugin=org.apache.bookkeeper.sasl.SASLClientProviderFactory
+
+```
+
+In this setting, `SASLClientProviderFactory` creates a BookKeeper SASL client in a Broker, and the Broker uses the created SASL client to authenticate with a Bookie node.
+
+Enter the following commands to add a section of `BookKeeper` configurations in the `pulsar_jaas.conf` that Pulsar Broker uses:
+
+```
+
+ BookKeeper {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarbroker.keytab"
+ principal="broker/localhost@EXAMPLE.COM";
+};
+
+```
+
+In this setting, the principal of Pulsar Broker and keyTab file indicates the role of Broker when you authenticate with Bookie.
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-oauth2.md b/site2/website-next/versioned_docs/version-2.7.1/security-oauth2.md
new file mode 100644
index 0000000..3596302
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-oauth2.md
@@ -0,0 +1,231 @@
+---
+id: security-oauth2
+title: Client authentication using OAuth 2.0 access tokens
+sidebar_label: "Authentication using OAuth 2.0 access tokens"
+original_id: security-oauth2
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+Pulsar supports authenticating clients using OAuth 2.0 access tokens. You can use OAuth 2.0 access tokens to identify a Pulsar client and associate the Pulsar client with some "principal" (or "role"), which is permitted to do some actions, such as publishing messages to a topic or consume messages from a topic.
+
+This module is used to support the Pulsar client authentication plugin for OAuth 2.0. After communicating with the Oauth 2.0 server, the Pulsar client gets an `access token` from the Oauth 2.0 server, and passes this `access token` to the Pulsar broker to do the authentication. The broker can use the `org.apache.pulsar.broker.authentication.AuthenticationProviderToken`. Or, you can add your own `AuthenticationProvider` to make it with this module.
+
+## Authentication provider configuration
+
+This library allows you to authenticate the Pulsar client by using an access token that is obtained from an OAuth 2.0 authorization service, which acts as a _token issuer_.
+
+### Authentication types
+
+The authentication type determines how to obtain an access token through an OAuth 2.0 authorization flow.
+
+#### Note
+> Currently, the Pulsar Java client only supports the `client_credentials` authentication type .
+
+#### Client credentials
+
+The following table lists parameters supported for the `client credentials` authentication type.
+
+| Parameter | Description | Example | Required or not |
+| --- | --- | --- | --- |
+| `type` | Oauth 2.0 authentication type. | `client_credentials` (default) | Optional |
+| `issuerUrl` | URL of the authentication provider which allows the Pulsar client to obtain an access token | `https://accounts.google.com` | Required |
+| `privateKey` | URL to a JSON credentials file | Support the following pattern formats: <br /> <li> `file:///path/to/file` </li><li>`file:/path/to/file` </li><li> `data:application/json;base64,<base64-encoded value>` </li>| Required |
+| `audience` | An OAuth 2.0 "resource server" identifier for the Pulsar cluster | `https://broker.example.com` | Required |
+
+The credentials file contains service account credentials used with the client authentication type. The following shows an example of a credentials file `credentials_file.json`.
+
+```json
+
+{
+ "type": "client_credentials",
+ "client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",
+ "client_secret": "on1uJ...k6F6R",
+ "client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",
+ "issuer_url": "https://accounts.google.com"
+}
+
+```
+
+In the above example, the authentication type is set to `client_credentials` by default. And the fields "client_id" and "client_secret" are required.
+
+### Typical original OAuth2 request mapping
+
+The following shows a typical original OAuth2 request, which is used to obtain the access token from the OAuth2 server.
+
+```bash
+
+curl --request POST \
+ --url https://dev-kt-aa9ne.us.auth0.com \
+ --header 'content-type: application/json' \
+ --data '{
+ "client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
+ "client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
+ "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
+ "grant_type":"client_credentials"}'
+
+```
+
+In the above example, the mapping relationship is shown as below.
+
+- The `issuerUrl` parameter in this plugin is mapped to `--url https://dev-kt-aa9ne.us.auth0.com`.
+- The `privateKey` file parameter in this plugin should at least contains the `client_id` and `client_secret` fields.
+- The `audience` parameter in this plugin is mapped to `"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"`.
+
+## Client Configuration
+
+You can use the OAuth2 authentication provider with the following Pulsar clients.
+
+### Java
+
+You can use the factory method to configure authentication for Pulsar Java client.
+
+```java
+
+String issuerUrl = "https://dev-kt-aa9ne.us.auth0.com";
+String credentialsUrl = "file:///path/to/KeyFile.json";
+String audience = "https://dev-kt-aa9ne.us.auth0.com/api/v2/";
+
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://broker.example.com:6650/")
+ .authentication(
+ AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credentialsUrl, 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":"./key/path/..","issuerUrl":"...","audience":"..."}");
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://broker.example.com:6650/")
+ .authentication(auth)
+ .build();
+
+```
+
+### C++ client
+
+The C++ client is similar to the Java client. You need to provide parameters of `issuerUrl`, `private_key` (the credentials file path), and the audience.
+
+```c++
+
+#include <pulsar/Client.h>
+
+pulsar::ClientConfiguration config;
+std::string params = R"({
+ "issuer_url": "https://dev-kt-aa9ne.us.auth0.com",
+ "private_key": "../../pulsar-broker/src/test/resources/authentication/token/cpp_credentials_file.json",
+ "audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/"})";
+
+config.setAuth(pulsar::AuthOauth2::create(params));
+
+pulsar::Client client("pulsar://broker.example.com:6650/", config);
+
+```
+
+### Go client
+
+To enable OAuth2 authentication in Go client, you need to configure OAuth2 authentication.
+This example shows how to configure OAuth2 authentication in Go client.
+
+```go
+
+oauth := pulsar.NewAuthenticationOAuth2(map[string]string{
+ "type": "client_credentials",
+ "issuerUrl": "https://dev-kt-aa9ne.us.auth0.com",
+ "audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/",
+ "privateKey": "/path/to/privateKey",
+ "clientId": "0Xx...Yyxeny",
+ })
+client, err := pulsar.NewClient(pulsar.ClientOptions{
+ URL: "pulsar://my-cluster:6650",
+ Authentication: oauth,
+})
+
+```
+
+### Python client
+
+To enable OAuth2 authentication in Python client, you need to configure OAuth2 authentication.
+This example shows how to configure OAuth2 authentication in Python client.
+
+```python
+
+from pulsar import Client, AuthenticationOauth2
+
+params = '''
+{
+ "issuer_url": "https://dev-kt-aa9ne.us.auth0.com",
+ "private_key": "/path/to/privateKey",
+ "audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/"
+}
+'''
+
+client = Client("pulsar://my-cluster:6650", authentication=AuthenticationOauth2(params))
+
+```
+
+## CLI configuration
+
+This section describes how to use Pulsar CLI tools to connect a cluster through OAuth2 authentication plugin.
+
+### pulsar-admin
+
+This example shows how to use pulsar-admin to connect to a cluster through OAuth2 authentication plugin.
+
+```shell script
+
+bin/pulsar-admin --admin-url https://streamnative.cloud:443 \
+--auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
+--auth-params '{"privateKey":"file:///path/to/key/file.json",
+ "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
+ "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
+tenants list
+
+```
+
+Set the `admin-url` parameter to the Web service URL. A Web service URLis a combination of the protocol, hostname and port ID, such as `pulsar://localhost:6650`.
+Set the `privateKey`, `issuerUrl`, and `audience` parameters to the values based on the configuration in the key file. For details, see [authentication types](#authentication-types).
+
+### pulsar-client
+
+This example shows how to use pulsar-client to connect to a cluster through OAuth2 authentication plugin.
+
+```shell script
+
+bin/pulsar-client \
+--url SERVICE_URL \
+--auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
+--auth-params '{"privateKey":"file:///path/to/key/file.json",
+ "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
+ "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
+produce test-topic -m "test-message" -n 10
+
+```
+
+Set the `admin-url` parameter to the Web service URL. A Web service URLis a combination of the protocol, hostname and port ID, such as `pulsar://localhost:6650`.
+Set the `privateKey`, `issuerUrl`, and `audience` parameters to the values based on the configuration in the key file. For details, see [authentication types](#authentication-types).
+
+### pulsar-perf
+
+This example shows how to use pulsar-perf to connect to a cluster through OAuth2 authentication plugin.
+
+```shell script
+
+bin/pulsar-perf produce --service-url pulsar+ssl://streamnative.cloud:6651 \
+--auth_plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
+--auth-params '{"privateKey":"file:///path/to/key/file.json",
+ "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
+ "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
+-r 1000 -s 1024 test-topic
+
+```
+
+Set the `admin-url` parameter to the Web service URL. A Web service URLis a combination of the protocol, hostname and port ID, such as `pulsar://localhost:6650`.
+Set the `privateKey`, `issuerUrl`, and `audience` parameters to the values based on the configuration in the key file. For details, see [authentication types](#authentication-types).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-overview.md b/site2/website-next/versioned_docs/version-2.7.1/security-overview.md
new file mode 100644
index 0000000..989c083
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-overview.md
@@ -0,0 +1,39 @@
+---
+id: security-overview
+title: Pulsar security overview
+sidebar_label: "Overview"
+original_id: security-overview
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+As the central message bus for a business, Apache Pulsar is frequently used for storing mission-critical data. Therefore, enabling security features in Pulsar is crucial.
+
+By default, Pulsar configures no encryption, authentication, or authorization. Any client can communicate to Apache Pulsar via plain text service URLs. So we must ensure that Pulsar accessing via these plain text service URLs is restricted to trusted clients only. In such cases, you can use Network segmentation and/or authorization ACLs to restrict access to trusted IPs. If you use neither, the state of cluster is wide open and anyone can access the cluster.
+
+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.
+
+The Pulsar broker validates the authentication credentials when a connection is established. After the initial connection is authenticated, the "principal" token is stored for authorization though the connection is not re-authenticated. The broker periodically checks the expiration status of every `ServerCnx` object. You can set the `authenticationRefreshCheckSeconds` on the broker to control the frequency to check the expiration status. By default, the `authenticationRefreshCheckSeconds [...]
+
+The broker supports learning whether a particular client supports authentication refreshing. If a client supports authentication refreshing and the credential is expired, the authentication provider calls the `refreshAuthentication` method to initiate the refreshing process. If a client does not support authentication refreshing and the credential is expired, the broker disconnects the client.
+
+You had better secure the service components in your Apache Pulsar deployment.
+
+## Role tokens
+
+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 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) to determine what the client is authorized to do.
+
+## Authentication providers
+
+Currently Pulsar supports the following authentication providers:
+
+- [TLS Authentication](security-tls-authentication)
+- [Athenz](security-athenz)
+- [Kerberos](security-kerberos)
+- [JSON Web Token Authentication](security-jwt)
+
+
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-tls-authentication.md b/site2/website-next/versioned_docs/version-2.7.1/security-tls-authentication.md
new file mode 100644
index 0000000..c1fe1d8
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-tls-authentication.md
@@ -0,0 +1,224 @@
+---
+id: security-tls-authentication
+title: Authentication using TLS
+sidebar_label: "Authentication using TLS"
+original_id: security-tls-authentication
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+## TLS authentication overview
+
+TLS authentication is an extension of [TLS transport encryption](security-tls-transport). Not only servers have keys and certs that the client uses to verify the identity of servers, clients also have keys and certs that the server uses to verify the identity of clients. You must have TLS transport encryption configured on your cluster before you can use TLS authentication. This guide assumes you already have TLS transport encryption configured.
+
+`Bouncy Castle Provider` provides TLS related cipher suites and algorithms in Pulsar. If you need [FIPS](https://www.bouncycastle.org/fips_faq.html) version of `Bouncy Castle Provider`, please reference [Bouncy Castle page](security-bouncy-castle).
+
+### Create client certificates
+
+Client certificates are generated using the certificate authority. Server certificates are also generated with the same certificate authority.
+
+The biggest difference between client certs and server certs is that the **common name** for the client certificate is the **role token** which that client is authenticated as.
+
+First, you need to enter the following command to generate the key :
+
+```bash
+
+$ openssl genrsa -out admin.key.pem 2048
+
+```
+
+Similar to the broker, the client expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format, so you need to convert it by entering the following command:
+
+```bash
+
+$ openssl pkcs8 -topk8 -inform PEM -outform PEM \
+ -in admin.key.pem -out admin.key-pk8.pem -nocrypt
+
+```
+
+Next, enter the command below to generate the certificate request. When you are asked for a **common name**, enter the **role token** that you want this key pair to authenticate a client as.
+
+```bash
+
+$ openssl req -config openssl.cnf \
+ -key admin.key.pem -new -sha256 -out admin.csr.pem
+
+```
+
+:::note
+
+If openssl.cnf is not specified, read [Certificate authority](http://pulsar.apache.org/docs/en/security-tls-transport/#certificate-authority) to get the openssl.cnf.
+
+:::
+
+Then, enter the command below to sign with request with the certificate authority. Note that the client certs uses the **usr_cert** extension, which allows the cert to be used for client authentication.
+
+```bash
+
+$ openssl ca -config openssl.cnf -extensions usr_cert \
+ -days 1000 -notext -md sha256 \
+ -in admin.csr.pem -out admin.cert.pem
+
+```
+
+You can get a cert, `admin.cert.pem`, and a key, `admin.key-pk8.pem` from this command. With `ca.cert.pem`, clients can use this cert and this key to authenticate themselves to brokers and proxies as the role token ``admin``.
+
+:::note
+
+If the "unable to load CA private key" error occurs and the reason of this error is "No such file or directory: /etc/pki/CA/private/cakey.pem" in this step. Try the command below:
+
+```bash
+
+$ cd /etc/pki/tls/misc/CA
+$ ./CA -newca
+
+```
+
+to generate `cakey.pem` .
+
+:::
+
+## Enable TLS authentication on brokers
+
+To configure brokers to authenticate clients, add the following parameters to `broker.conf`, alongside [the configuration to enable tls transport](security-tls-transport.md#broker-configuration):
+
+```properties
+
+# Configuration to enable authentication
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
+
+# operations and publish/consume from all topics
+superUserRoles=admin
+
+# Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters
+brokerClientTlsEnabled=true
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
+brokerClientAuthenticationParameters={"tlsCertFile":"/path/my-ca/admin.cert.pem","tlsKeyFile":"/path/my-ca/admin.key-pk8.pem"}
+brokerClientTrustCertsFilePath=/path/my-ca/certs/ca.cert.pem
+
+```
+
+## Enable TLS authentication on proxies
+
+To configure proxies to authenticate clients, add the following parameters to `proxy.conf`, alongside [the configuration to enable tls transport](security-tls-transport.md#proxy-configuration):
+
+The proxy should have its own client key pair for connecting to brokers. You need to configure the role token for this key pair in the ``proxyRoles`` of the brokers. See the [authorization guide](security-authorization) for more details.
+
+```properties
+
+# For clients connecting to the proxy
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
+
+# For the proxy to connect to brokers
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
+brokerClientAuthenticationParameters=tlsCertFile:/path/to/proxy.cert.pem,tlsKeyFile:/path/to/proxy.key-pk8.pem
+
+```
+
+## Client configuration
+
+When you use TLS authentication, client connects via TLS transport. You need to configure the client to use ```https://``` and 8443 port for the web service URL, ```pulsar+ssl://``` and 6651 port for the broker service URL.
+
+### CLI tools
+
+[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](reference-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 TLS authentication with the CLI tools of Pulsar:
+
+```
+
+webServiceUrl=https://broker.example.com:8443/
+brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
+useTls=true
+tlsAllowInsecureConnection=false
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
+authParams=tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem
+
+```
+
+### Java client
+
+```
+
+import org.apache.pulsar.client.api.PulsarClient;
+
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar+ssl://broker.example.com:6651/")
+ .enableTls(true)
+ .tlsTrustCertsFilePath("/path/to/ca.cert.pem")
+ .authentication("org.apache.pulsar.client.impl.auth.AuthenticationTls",
+ "tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem")
+ .build();
+
+```
+
+### Python client
+
+```
+
+from pulsar import Client, AuthenticationTLS
+
+auth = AuthenticationTLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem")
+client = Client("pulsar+ssl://broker.example.com:6651/",
+ tls_trust_certs_file_path="/path/to/ca.cert.pem",
+ tls_allow_insecure_connection=False,
+ authentication=auth)
+
+```
+
+### C++ client
+
+```
+
+#include <pulsar/Client.h>
+
+pulsar::ClientConfiguration config;
+config.setUseTls(true);
+config.setTlsTrustCertsFilePath("/path/to/ca.cert.pem");
+config.setTlsAllowInsecureConnection(false);
+
+pulsar::AuthenticationPtr auth = pulsar::AuthTls::create("/path/to/my-role.cert.pem",
+ "/path/to/my-role.key-pk8.pem")
+config.setAuth(auth);
+
+pulsar::Client client("pulsar+ssl://broker.example.com:6651/", config);
+
+```
+
+### Node.js client
+
+```
+
+const Pulsar = require('pulsar-client');
+
+(async () => {
+ const auth = new Pulsar.AuthenticationTls({
+ certificatePath: '/path/to/my-role.cert.pem',
+ privateKeyPath: '/path/to/my-role.key-pk8.pem',
+ });
+
+ const client = new Pulsar.Client({
+ serviceUrl: 'pulsar+ssl://broker.example.com:6651/',
+ authentication: auth,
+ tlsTrustCertsFilePath: '/path/to/ca.cert.pem',
+ });
+})();
+
+```
+
+### C# client
+
+```
+
+var clientCertificate = new X509Certificate2("admin.pfx");
+var client = PulsarClient.Builder()
+ .AuthenticateUsingClientCertificate(clientCertificate)
+ .Build();
+
+```
+
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-tls-keystore.md b/site2/website-next/versioned_docs/version-2.7.1/security-tls-keystore.md
new file mode 100644
index 0000000..94f20d6
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-tls-keystore.md
@@ -0,0 +1,326 @@
+---
+id: security-tls-keystore
+title: Using TLS with KeyStore configure
+sidebar_label: "Using TLS with KeyStore configure"
+original_id: security-tls-keystore
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+## Overview
+
+Apache Pulsar supports [TLS encryption](security-tls-transport.md) and [TLS authentication](security-tls-authentication) between clients and Apache Pulsar service.
+By default it uses PEM format file configuration. This page tries to describe use [KeyStore](https://en.wikipedia.org/wiki/Java_KeyStore) type configure for TLS.
+
+
+## TLS encryption with KeyStore configure
+
+### Generate TLS key and certificate
+
+The first step of deploying TLS is to generate the key and the certificate for each machine in the cluster.
+You can use Java’s `keytool` utility to accomplish this task. We will generate the key into a temporary keystore
+initially for broker, so that we can export and sign it later with CA.
+
+```shell
+
+keytool -keystore broker.keystore.jks -alias localhost -validity {validity} -genkeypair -keyalg RSA
+
+```
+
+You need to specify two parameters in the above command:
+
+1. `keystore`: the keystore file that stores the certificate. The *keystore* file contains the private key of
+ the certificate; hence, it needs to be kept safely.
+2. `validity`: the valid time of the certificate in days.
+
+> Ensure that common name (CN) matches exactly with the fully qualified domain name (FQDN) of the server.
+The client compares the CN with the DNS domain name to ensure that it is indeed connecting to the desired server, not a malicious one.
+
+### Creating your own CA
+
+After the first step, each broker in the cluster has a public-private key pair, and a certificate to identify the machine.
+The certificate, however, is unsigned, which means that an attacker can create such a certificate to pretend to be any machine.
+
+Therefore, it is important to prevent forged certificates by signing them for each machine in the cluster.
+A `certificate authority (CA)` is responsible for signing certificates. CA works likes a government that issues passports —
+the government stamps (signs) each passport so that the passport becomes difficult to forge. Other governments verify the stamps
+to ensure the passport is authentic. Similarly, the CA signs the certificates, and the cryptography guarantees that a signed
+certificate is computationally difficult to forge. Thus, as long as the CA is a genuine and trusted authority, the clients have
+high assurance that they are connecting to the authentic machines.
+
+```shell
+
+openssl req -new -x509 -keyout ca-key -out ca-cert -days 365
+
+```
+
+The generated CA is simply a *public-private* key pair and certificate, and it is intended to sign other certificates.
+
+The next step is to add the generated CA to the clients' truststore so that the clients can trust this CA:
+
+```shell
+
+keytool -keystore client.truststore.jks -alias CARoot -import -file ca-cert
+
+```
+
+NOTE: If you configure the brokers to require client authentication by setting `tlsRequireTrustedClientCertOnConnect` to `true` on the
+broker configuration, then you must also provide a truststore for the brokers and it should have all the CA certificates that clients keys were signed by.
+
+```shell
+
+keytool -keystore broker.truststore.jks -alias CARoot -import -file ca-cert
+
+```
+
+In contrast to the keystore, which stores each machine’s own identity, the truststore of a client stores all the certificates
+that the client should trust. Importing a certificate into one’s truststore also means trusting all certificates that are signed
+by that certificate. As the analogy above, trusting the government (CA) also means trusting all passports (certificates) that
+it has issued. This attribute is called the chain of trust, and it is particularly useful when deploying TLS on a large BookKeeper cluster.
+You can sign all certificates in the cluster with a single CA, and have all machines share the same truststore that trusts the CA.
+That way all machines can authenticate all other machines.
+
+
+### Signing the certificate
+
+The next step is to sign all certificates in the keystore with the CA we generated. First, you need to export the certificate from the keystore:
+
+```shell
+
+keytool -keystore broker.keystore.jks -alias localhost -certreq -file cert-file
+
+```
+
+Then sign it with the CA:
+
+```shell
+
+openssl x509 -req -CA ca-cert -CAkey ca-key -in cert-file -out cert-signed -days {validity} -CAcreateserial -passin pass:{ca-password}
+
+```
+
+Finally, you need to import both the certificate of the CA and the signed certificate into the keystore:
+
+```shell
+
+keytool -keystore broker.keystore.jks -alias CARoot -import -file ca-cert
+keytool -keystore broker.keystore.jks -alias localhost -import -file cert-signed
+
+```
+
+The definitions of the parameters are the following:
+
+1. `keystore`: the location of the keystore
+2. `ca-cert`: the certificate of the CA
+3. `ca-key`: the private key of the CA
+4. `ca-password`: the passphrase of the CA
+5. `cert-file`: the exported, unsigned certificate of the broker
+6. `cert-signed`: the signed certificate of the broker
+
+### Configuring brokers
+
+Brokers enable TLS by provide valid `brokerServicePortTls` and `webServicePortTls`, and also need set `tlsEnabledWithKeyStore` to `true` for using KeyStore type configuration.
+Besides this, KeyStore path, KeyStore password, TrustStore path, and TrustStore password need to provided.
+And since broker will create internal client/admin client to communicate with other brokers, user also need to provide config for them, this is similar to how user config the outside client/admin-client.
+If `tlsRequireTrustedClientCertOnConnect` is `true`, broker will reject the Connection if the Client Certificate is not trusted.
+
+The following TLS configs are needed on the broker side:
+
+```properties
+
+tlsEnabledWithKeyStore=true
+# key store
+tlsKeyStoreType=JKS
+tlsKeyStore=/var/private/tls/broker.keystore.jks
+tlsKeyStorePassword=brokerpw
+
+# trust store
+tlsTrustStoreType=JKS
+tlsTrustStore=/var/private/tls/broker.truststore.jks
+tlsTrustStorePassword=brokerpw
+
+# internal client/admin-client config
+brokerClientTlsEnabled=true
+brokerClientTlsEnabledWithKeyStore=true
+brokerClientTlsTrustStoreType=JKS
+brokerClientTlsTrustStore=/var/private/tls/client.truststore.jks
+brokerClientTlsTrustStorePassword=clientpw
+
+```
+
+NOTE: it is important to restrict access to the store files via filesystem permissions.
+
+Optional settings that may worth consider:
+
+1. tlsClientAuthentication=false: Enable/Disable using TLS for authentication. This config when enabled will authenticate the other end
+ of the communication channel. It should be enabled on both brokers and clients for mutual TLS.
+2. tlsCiphers=[TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256], A cipher suite is a named combination of authentication, encryption, MAC and key exchange
+ algorithm used to negotiate the security settings for a network connection using TLS network protocol. By default,
+ it is null. [OpenSSL Ciphers](https://www.openssl.org/docs/man1.0.2/apps/ciphers.html)
+ [JDK Ciphers](http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites)
+3. tlsProtocols=[TLSv1.2,TLSv1.1,TLSv1] (list out the TLS protocols that you are going to accept from clients).
+ By default, it is not set.
+
+### Configuring Clients
+
+This is similar to [TLS encryption configuing for client with PEM type](security-tls-transport.md#Client configuration).
+For a a minimal configuration, user need to provide the TrustStore information.
+
+e.g.
+1. for [Command-line tools](reference-cli-tools) like [`pulsar-admin`](reference-cli-tools#pulsar-admin), [`pulsar-perf`](reference-cli-tools#pulsar-perf), and [`pulsar-client`](reference-cli-tools#pulsar-client) use the `conf/client.conf` config file in a Pulsar installation.
+
+ ```properties
+
+ webServiceUrl=https://broker.example.com:8443/
+ brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
+ useKeyStoreTls=true
+ tlsTrustStoreType=JKS
+ tlsTrustStorePath=/var/private/tls/client.truststore.jks
+ tlsTrustStorePassword=clientpw
+
+ ```
+
+1. for java client
+
+ ```java
+
+ import org.apache.pulsar.client.api.PulsarClient;
+
+ PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar+ssl://broker.example.com:6651/")
+ .enableTls(true)
+ .useKeyStoreTls(true)
+ .tlsTrustStorePath("/var/private/tls/client.truststore.jks")
+ .tlsTrustStorePassword("clientpw")
+ .allowTlsInsecureConnection(false)
+ .build();
+
+ ```
+
+1. for java admin client
+
+```java
+
+ PulsarAdmin amdin = PulsarAdmin.builder().serviceHttpUrl("https://broker.example.com:8443")
+ .useKeyStoreTls(true)
+ .tlsTrustStorePath("/var/private/tls/client.truststore.jks")
+ .tlsTrustStorePassword("clientpw")
+ .allowTlsInsecureConnection(false)
+ .build();
+
+```
+
+## TLS authentication with KeyStore configure
+
+This similar to [TLS authentication with PEM type](security-tls-authentication)
+
+### broker authentication config
+
+`broker.conf`
+
+```properties
+
+# Configuration to enable authentication
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
+
+# this should be the CN for one of client keystore.
+superUserRoles=admin
+
+# Enable KeyStore type
+tlsEnabledWithKeyStore=true
+requireTrustedClientCertOnConnect=true
+
+# key store
+tlsKeyStoreType=JKS
+tlsKeyStore=/var/private/tls/broker.keystore.jks
+tlsKeyStorePassword=brokerpw
+
+# trust store
+tlsTrustStoreType=JKS
+tlsTrustStore=/var/private/tls/broker.truststore.jks
+tlsTrustStorePassword=brokerpw
+
+# internal client/admin-client config
+brokerClientTlsEnabled=true
+brokerClientTlsEnabledWithKeyStore=true
+brokerClientTlsTrustStoreType=JKS
+brokerClientTlsTrustStore=/var/private/tls/client.truststore.jks
+brokerClientTlsTrustStorePassword=clientpw
+# internal auth config
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls
+brokerClientAuthenticationParameters={"keyStoreType":"JKS","keyStorePath":"/var/private/tls/client.keystore.jks","keyStorePassword":"clientpw"}
+# currently websocket not support keystore type
+webSocketServiceEnabled=false
+
+```
+
+### client authentication configuring
+
+Besides the TLS encryption configuring. The main work is configuring the KeyStore, which contains a valid CN as client role, for client.
+
+e.g.
+1. for [Command-line tools](reference-cli-tools) like [`pulsar-admin`](reference-cli-tools#pulsar-admin), [`pulsar-perf`](reference-cli-tools#pulsar-perf), and [`pulsar-client`](reference-cli-tools#pulsar-client) use the `conf/client.conf` config file in a Pulsar installation.
+
+ ```properties
+
+ webServiceUrl=https://broker.example.com:8443/
+ brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
+ useKeyStoreTls=true
+ tlsTrustStoreType=JKS
+ tlsTrustStorePath=/var/private/tls/client.truststore.jks
+ tlsTrustStorePassword=clientpw
+ authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls
+ authParams={"keyStoreType":"JKS","keyStorePath":"/path/to/keystorefile","keyStorePassword":"keystorepw"}
+
+ ```
+
+1. for java client
+
+ ```java
+
+ import org.apache.pulsar.client.api.PulsarClient;
+
+ PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar+ssl://broker.example.com:6651/")
+ .enableTls(true)
+ .useKeyStoreTls(true)
+ .tlsTrustStorePath("/var/private/tls/client.truststore.jks")
+ .tlsTrustStorePassword("clientpw")
+ .allowTlsInsecureConnection(false)
+ .authentication(
+ "org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls",
+ "keyStoreType:JKS,keyStorePath:/var/private/tls/client.keystore.jks,keyStorePassword:clientpw")
+ .build();
+
+ ```
+
+1. for java admin client
+
+ ```java
+
+ PulsarAdmin amdin = PulsarAdmin.builder().serviceHttpUrl("https://broker.example.com:8443")
+ .useKeyStoreTls(true)
+ .tlsTrustStorePath("/var/private/tls/client.truststore.jks")
+ .tlsTrustStorePassword("clientpw")
+ .allowTlsInsecureConnection(false)
+ .authentication(
+ "org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls",
+ "keyStoreType:JKS,keyStorePath:/var/private/tls/client.keystore.jks,keyStorePassword:clientpw")
+ .build();
+
+ ```
+
+## Enabling TLS Logging
+
+You can enable TLS debug logging at the JVM level by starting the brokers and/or clients with `javax.net.debug` system property. For example:
+
+```shell
+
+-Djavax.net.debug=all
+
+```
+
+You can find more details on this in [Oracle documentation](http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html) on [debugging SSL/TLS connections](http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html).
diff --git a/site2/website-next/versioned_docs/version-2.7.1/security-tls-transport.md b/site2/website-next/versioned_docs/version-2.7.1/security-tls-transport.md
new file mode 100644
index 0000000..22e5d4b
--- /dev/null
+++ b/site2/website-next/versioned_docs/version-2.7.1/security-tls-transport.md
@@ -0,0 +1,292 @@
+---
+id: security-tls-transport
+title: Transport Encryption using TLS
+sidebar_label: "Transport Encryption using TLS"
+original_id: security-tls-transport
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+## TLS overview
+
+By default, Apache Pulsar clients communicate with the Apache Pulsar service in plain text. This means that all data is sent in the clear. You can use TLS to encrypt this traffic to protect the traffic from the snooping of a man-in-the-middle attacker.
+
+You can also configure TLS for both encryption and authentication. Use this guide to configure just TLS transport encryption and refer to [here](security-tls-authentication.md) for TLS authentication configuration. Alternatively, you can use [another authentication mechanism](security-athenz) on top of TLS transport encryption.
+
+> Note that enabling TLS may impact the performance due to encryption overhead.
+
+## TLS concepts
+
+TLS is a form of [public key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). Using key pairs consisting of a public key and a private key can perform the encryption. The public key encrpyts the messages and the private key decrypts the messages.
+
+To use TLS transport encryption, you need two kinds of key pairs, **server key pairs** and a **certificate authority**.
+
+You can use a third kind of key pair, **client key pairs**, for [client authentication](security-tls-authentication).
+
+You should store the **certificate authority** private key in a very secure location (a fully encrypted, disconnected, air gapped computer). As for the certificate authority public key, the **trust cert**, you can freely shared it.
+
+For both client and server key pairs, the administrator first generates a private key and a certificate request, then uses the certificate authority private key to sign the certificate request, finally generates a certificate. This certificate is the public key for the server/client key pair.
+
+For TLS transport encryption, the clients can use the **trust cert** to verify that the server has a key pair that the certificate authority signed when the clients are talking to the server. A man-in-the-middle attacker does not have access to the certificate authority, so they couldn't create a server with such a key pair.
+
+For TLS authentication, the server uses the **trust cert** to verify that the client has a key pair that the certificate authority signed. The common name of the **client cert** is then used as the client's role token (see [Overview](security-overview)).
+
+`Bouncy Castle Provider` provides cipher suites and algorithms in Pulsar. If you need [FIPS](https://www.bouncycastle.org/fips_faq.html) version of `Bouncy Castle Provider`, please reference [Bouncy Castle page](security-bouncy-castle).
+
+## Create TLS certificates
+
+Creating TLS certificates for Pulsar involves creating a [certificate authority](#certificate-authority) (CA), [server certificate](#server-certificate), and [client certificate](#client-certificate).
+
+Follow the guide below to set up a certificate authority. You can also refer to plenty of resources on the internet for more details. We recommend [this guide](https://jamielinux.com/docs/openssl-certificate-authority/index.html) for your detailed reference.
+
+### Certificate authority
+
+1. Create the certificate for the CA. You can use CA to sign both the broker and client certificates. This ensures that each party will trust the others. You should store CA in a very secure location (ideally completely disconnected from networks, air gapped, and fully encrypted).
+
+2. Entering the following command to create a directory for your CA, and place [this openssl configuration file](https://github.com/apache/pulsar/tree/master/site2/website/static/examples/openssl.cnf) in the directory. You may want to modify the default answers for company name and department in the configuration file. Export the location of the CA directory to the environment variable, CA_HOME. The configuration file uses this environment variable to find the rest of the files and direc [...]
+
+```bash
+
+mkdir my-ca
+cd my-ca
+wget https://raw.githubusercontent.com/apache/pulsar/master/site2/website/static/examples/openssl.cnf
+export CA_HOME=$(pwd)
+
+```
+
+3. Enter the commands below to create the necessary directories, keys and certs.
+
+```bash
+
+mkdir certs crl newcerts private
+chmod 700 private/
+touch index.txt
+echo 1000 > serial
+openssl genrsa -aes256 -out private/ca.key.pem 4096
+chmod 400 private/ca.key.pem
+openssl req -config openssl.cnf -key private/ca.key.pem \
+ -new -x509 -days 7300 -sha256 -extensions v3_ca \
+ -out certs/ca.cert.pem
+chmod 444 certs/ca.cert.pem
+
+```
+
+4. After you answer the question prompts, CA-related files are stored in the `./my-ca` directory. Within that directory:
+
+* `certs/ca.cert.pem` is the public certificate. This public certificates is meant to be distributed to all parties involved.
+* `private/ca.key.pem` is the private key. You only need it when you are signing a new certificate for either broker or clients and you must safely guard this private key.
+
+### Server certificate
+
+Once you have created a CA certificate, you can create certificate requests and sign them with the CA.
+
+The following commands ask you a few questions and then create the certificates. When you are asked for the common name, you should match the hostname of the broker. You can also use a wildcard to match a group of broker hostnames, for example, `*.broker.usw.example.com`. This ensures that multiple machines can reuse the same certificate.
+
+> #### Tips
+>
+> Sometimes matching the hostname is not possible or makes no sense,
+> such as when you create the brokers with random hostnames, or you
+> plan to connect to the hosts via their IP. In these cases, you
+> should configure the client to disable TLS hostname verification. For more
+> details, you can see [the host verification section in client configuration](#hostname-verification).
+
+1. Enter the command below to generate the key.
+
+```bash
+
+openssl genrsa -out broker.key.pem 2048
+
+```
+
+The broker expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format, so enter the following command to convert it.
+
+```bash
+
+openssl pkcs8 -topk8 -inform PEM -outform PEM \
+ -in broker.key.pem -out broker.key-pk8.pem -nocrypt
+
+```
+
+2. Enter the following command to generate the certificate request.
+
+```bash
+
+openssl req -config openssl.cnf \
+ -key broker.key.pem -new -sha256 -out broker.csr.pem
+
+```
+
+3. Sign it with the certificate authority by entering the command below.
+
+```bash
+
+openssl ca -config openssl.cnf -extensions server_cert \
+ -days 1000 -notext -md sha256 \
+ -in broker.csr.pem -out broker.cert.pem
+
+```
+
+At this point, you have a cert, `broker.cert.pem`, and a key, `broker.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS transport encryption for your broker and proxy nodes.
+
+## Broker Configuration
+
+To configure a Pulsar [broker](reference-terminology.md#broker) to use TLS transport encryption, you need to make some changes to `broker.conf`, which locates in the `conf` directory of your [Pulsar installation](getting-started-standalone).
+
+Add these values to the configuration file (substituting the appropriate certificate paths where necessary):
+
+```properties
+
+tlsEnabled=true
+tlsCertificateFilePath=/path/to/broker.cert.pem
+tlsKeyFilePath=/path/to/broker.key-pk8.pem
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+
+```
+
+> You can find a full list of parameters available in the `conf/broker.conf` file,
+> as well as the default values for those parameters, in [Broker Configuration](reference-configuration.md#broker)
+>
+### TLS Protocol Version and Cipher
+
+You can configure the broker (and proxy) to require specific TLS protocol versions and ciphers for TLS negiotation. You can use the TLS protocol versions and ciphers to stop clients from requesting downgraded TLS protocol versions or ciphers that may have weaknesses.
+
+Both the TLS protocol versions and cipher properties can take multiple values, separated by commas. The possible values for protocol version and ciphers depend on the TLS provider that you are using. Pulsar uses OpenSSL if the OpenSSL is available, but if the OpenSSL is not available, Pulsar defaults back to the JDK implementation.
+
+```properties
+
+tlsProtocols=TLSv1.2,TLSv1.1
+tlsCiphers=TLS_DH_RSA_WITH_AES_256_GCM_SHA384,TLS_DH_RSA_WITH_AES_256_CBC_SHA
+
+```
+
+OpenSSL currently supports ```SSL2```, ```SSL3```, ```TLSv1```, ```TLSv1.1``` and ```TLSv1.2``` for the protocol version. You can acquire a list of supported cipher from the openssl ciphers command, i.e. ```openssl ciphers -tls_v2```.
+
+For JDK 8, you can obtain a list of supported values from the documentation:
+- [TLS protocol](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#SSLContext)
+- [Ciphers](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites)
+
+## Proxy Configuration
+
+Proxies need to configure TLS in two directions, for clients connecting to the proxy, and for the proxy connecting to brokers.
+
+```
+
+# For clients connecting to the proxy
+tlsEnabledInProxy=true
+tlsCertificateFilePath=/path/to/broker.cert.pem
+tlsKeyFilePath=/path/to/broker.key-pk8.pem
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+
+# For the proxy to connect to brokers
+tlsEnabledWithBroker=true
+brokerClientTrustCertsFilePath=/path/to/ca.cert.pem
+
+```
+
+## Client configuration
+
+When you enable the TLS transport encryption, you need to configure the client to use ```
+
+As the server certificate that you generated above does not belong to any of the default trust chains, you also need to either specify the path the **trust cert** (recommended), or tell the client to allow untrusted server certs.
+
+### Hostname verification
+
+Hostname verification is a TLS security feature whereby a client can refuse to connect to a server if the "CommonName" does not match the hostname to which the hostname is connecting. By default, Pulsar clients disable hostname verification, as it requires that each broker has a DNS record and a unique cert.
+
+Moreover, as the administrator has full control of the certificate authority, a bad actor is unlikely to be able to pull off a man-in-the-middle attack. "allowInsecureConnection" allows the client to connect to servers whose cert has not been signed by an approved CA. The client disables "allowInsecureConnection" by default, and you should always disable "allowInsecureConnection" in production environments. As long as you disable "allowInsecureConnection", a man-in-the-middle attack requ [...]
+
+One scenario where you may want to enable hostname verification is where you have multiple proxy nodes behind a VIP, and the VIP has a DNS record, for example, pulsar.mycompany.com. In this case, you can generate a TLS cert with pulsar.mycompany.com as the "CommonName," and then enable hostname verification on the client.
+
+The examples below show hostname verification being disabled for the Java client, though you can omit this as the client disables the hostname verification by default. C++/python/Node.js clients do now allow configuring this at the moment.
+
+### CLI tools
+
+[Command-line tools](reference-cli-tools) like [`pulsar-admin`](reference-cli-tools.md#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 TLS transport with the CLI tools of Pulsar:
+
+```properties
+
+webServiceUrl=https://broker.example.com:8443/
+brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
+useTls=true
+tlsAllowInsecureConnection=false
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+tlsEnableHostnameVerification=false
+
+```
+
+#### Java client
+
+```java
+
+import org.apache.pulsar.client.api.PulsarClient;
+
+PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar+ssl://broker.example.com:6651/")
+ .enableTls(true)
+ .tlsTrustCertsFilePath("/path/to/ca.cert.pem")
+ .enableTlsHostnameVerification(false) // false by default, in any case
+ .allowTlsInsecureConnection(false) // false by default, in any case
+ .build();
+
+```
+
+#### Python client
+
+```python
+
+from pulsar import Client
+
+client = Client("pulsar+ssl://broker.example.com:6651/",
+ tls_hostname_verification=True,
+ tls_trust_certs_file_path="/path/to/ca.cert.pem",
+ tls_allow_insecure_connection=False) // defaults to false from v2.2.0 onwards
+
+```
+
+#### C++ client
+
+```c++
+
+#include <pulsar/Client.h>
+
+ClientConfiguration config = ClientConfiguration();
+config.setUseTls(true); // shouldn't be needed soon
+config.setTlsTrustCertsFilePath(caPath);
+config.setTlsAllowInsecureConnection(false);
+config.setAuth(pulsar::AuthTls::create(clientPublicKeyPath, clientPrivateKeyPath));
+config.setValidateHostName(true);
+
+```
+
+#### Node.js client
+
+```JavaScript
+
+const Pulsar = require('pulsar-client');
+
+(async () => {
+ const client = new Pulsar.Client({
+ serviceUrl: 'pulsar+ssl://broker.example.com:6651/',
+ tlsTrustCertsFilePath: '/path/to/ca.cert.pem',
+ });
+})();
+
+```
+
+#### C# client
+
+```c#
+
+var certificate = new X509Certificate2("ca.cert.pem");
+var client = PulsarClient.Builder()
+ .TrustedCertificateAuthority(certificate) //If the CA is not trusted on the host, you can add it explicitly.
+ .VerifyCertificateAuthority(true) //Default is 'true'
+ .VerifyCertificateName(false) //Default is 'false'
+ .Build();
+
+```
+
diff --git a/site2/website-next/versioned_sidebars/version-2.7.1-sidebars.json b/site2/website-next/versioned_sidebars/version-2.7.1-sidebars.json
index a95a781..fc2a107 100644
--- a/site2/website-next/versioned_sidebars/version-2.7.1-sidebars.json
+++ b/site2/website-next/versioned_sidebars/version-2.7.1-sidebars.json
@@ -333,6 +333,60 @@
"id": "version-2.7.1/administration-isolation"
}
]
+ },
+ {
+ "type": "category",
+ "label": "Security",
+ "items": [
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-overview"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-tls-transport"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-tls-authentication"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-tls-keystore"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-jwt"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-athenz"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-kerberos"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-oauth2"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-authorization"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-encryption"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-extending"
+ },
+ {
+ "type": "doc",
+ "id": "version-2.7.1/security-bouncy-castle"
+ }
+ ]
}
]
}
\ No newline at end of file