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 <[email protected]>
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 <[email protected]>
* [website][upgrade]feat: docs migration - 2.7.1 / administration
Signed-off-by: LiLi <[email protected]>
* [website][upgrade]feat: docs migration - 2.7.1 / security
Signed-off-by: LiLi <[email protected]>
---
.../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/[email protected]";
+};
+
+ PulsarClient {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarclient.keytab"
+ principal="client/[email protected]";
+};
+
+```
+
+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/[email protected]";
+};
+
+ PulsarProxy {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarproxy.keytab"
+ principal="proxy/[email protected]";
+};
+
+ PulsarClient {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarclient.keytab"
+ principal="client/[email protected]";
+};
+
+```
+
+### 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/[email protected]";
+};
+
+```
+
+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/[email protected]";
+};
+
+```
+
+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-abcdefghijklmnopqrstuvw...@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
