[website][upgrade]feat: docs migration - 2.7.1 / security

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
+
+```
+

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 authenticated with the proxy.
+
+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 to access anything.
+
+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();
+
+```
+

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`.
+