sijie closed pull request #2220: Rework TLS docs to separate concerns
URL: https://github.com/apache/incubator-pulsar/pull/2220
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
index bcd58c4676..c38afc524d 100644
--- a/site/_data/sidebar.yaml
+++ b/site/_data/sidebar.yaml
@@ -99,7 +99,9 @@ groups:
docs:
- title: Overview
endpoint: overview
- - title: Encryption and Authentication using TLS
+ - title: Transport Encryption with TLS
+ endpoint: tls-transport
+ - title: Authentication using TLS
endpoint: tls
- title: Authentication using Athenz
endpoint: athenz
diff --git a/site/docs/latest/security/authorization.md
b/site/docs/latest/security/authorization.md
index c0c58eeb62..393284e8ab 100644
--- a/site/docs/latest/security/authorization.md
+++ b/site/docs/latest/security/authorization.md
@@ -25,15 +25,51 @@ tags: [admin, authentication, authorization, athenz, tls,
java, cpp]
-->
In Pulsar, the [authentication provider](../overview#authentication-providers)
is charged with properly identifying clients and
-associating them with [role tokens](../overview#role-tokens). *Authorization*
is the process that determines *what* clients are able to do.
+associating them with [role tokens](../overview#role-tokens). If only
authentication is enabled, an authenticated role token will have the ability to
access all resources in the cluster. *Authorization* is the process that
determines *what* clients are able to do.
-Authorization in Pulsar is managed at the {% popover tenant %} level, which
means that you can have multiple authorization schemes active
-in a single Pulsar instance. You could, for example, create a `shopping`
tenant that has one set of [roles](../overview#role-tokens)
-and applies to a shopping application used by your company, while an
`inventory` tenant would be used only by an inventory application.
+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.
-{% include message.html id="properties_multiple_clusters" %}
+When a {% popover tenant %} is created by a superuser, 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.
-## Creating a new tenant
+## Broker and Proxy Setup
+
+### Enabling Authorization and Assigning Superusers
+
+Authorization is enabled and superusers are assigned in the broker
([`conf/broker.conf`](../../reference/Configuration#broker)) and proxy
([`conf/proxy.conf`](../../reference/Configuration#proxy)) configuration files.
+
+```properties
+authorizationEnabled=true
+superUserRoles=my-super-user-1,my-super-user-2
+```
+
+{% include message.html id="broker_conf_doc" %}
+
+Typically, superuser roles are used for administrators and clients but also
for broker-to-broker authorization. When using
[geo-replication](../GeoReplication), every broker needs to be able to publish
to all the other clusters' topics.
+
+### Proxy Roles
+
+By default, the broker treats the connection between a proxy and the broker as
a normal user connection. The user is authenticated as the role configured in
```proxy.conf``` (see ["Enabling TLS Authentication on
Proxies"](../tls#-on-proxies)). However, this is rarely the behaviour that the
user desires when connecting to the cluster through a proxy. 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 this. Proxy roles are specified in the
broker configuration file,
[`conf/broker.conf`](../../reference/Configuration#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. If this information, which we call the *original
principal*, is missing, the client will not be able to access anything.
+
+Both the *proxy role* and the *original principle* must be authorized to
access a resource for that resource to be accessible via the proxy.
Administrators can take two approaches to this.
+
+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 ```proxy1```,
when a tenant is created by the superuser, ```proxy1``` should be specified 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, ```proxy1``` should also be granted the same permissions.
+
+Another approach is to make the proxy role a superuser. This will allow the
proxy to access all resources. The client will still need to authenticate with
the proxy, and all requests made through the proxy will 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.
+
+Roles can be specified as proxy roles in
[`conf/broker.conf`](../../reference/Configuration#broker).
+
+```properties
+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
+```
+
+## Administering Tenants
+
+### Creating a new tenant
A Pulsar {% popover tenant %} is typically provisioned by Pulsar {% popover
instance %} administrators or by some kind of self-service portal.
@@ -53,26 +89,11 @@ The structure of topic names in Pulsar reflects the
hierarchy between tenants, c
{% include topic.html ten="tenant" n="namespace" t="topic" %}
-## Managing permissions
+### Managing permissions
{% include explanations/permissions.md %}
-## Superusers
-
-In Pulsar you can assign certain roles to be *superusers* of the system. A
superuser is allowed to perform all administrative tasks on all tenants and
namespaces, as well as to publish and subscribe to all topics.
-
-Superusers are configured in the broker configuration file in
[`conf/broker.conf`](../../reference/Configuration#broker) configuration file,
using the
[`superUserRoles`](../../reference/Configuration#broker-superUserRoles)
parameter:
-
-```tenants
-superUserRoles=my-super-user-1,my-super-user-2
-```
-
-{% include message.html id="broker_conf_doc" %}
-
-Typically, superuser roles are used for administrators and clients but also
for broker-to-broker authorization. When using
[geo-replication](../GeoReplication), every broker
-needs to be able to publish to other clusters' topics.
-
-## Pulsar admin authentication
+### Pulsar admin authentication
```java
String authPluginClassName = "com.org.MyAuthPluginClass";
diff --git a/site/docs/latest/security/openssl.cnf
b/site/docs/latest/security/openssl.cnf
new file mode 100644
index 0000000000..eee8a47298
--- /dev/null
+++ b/site/docs/latest/security/openssl.cnf
@@ -0,0 +1,152 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+#
+# Configuration file for testing certificate authority.
+# The environment variable, CA_HOME, must be set to point to the directory
+# containing this file before running any openssl commands.
+#
+[ ca ]
+# `man ca`
+default_ca = CA_default
+
+[ CA_default ]
+# Directory and file locations.
+dir = $ENV::CA_HOME
+certs = $dir/certs
+crl_dir = $dir/crl
+new_certs_dir = $dir/newcerts
+database = $dir/index.txt
+serial = $dir/serial
+RANDFILE = $dir/private/.rand
+
+# The root key and root certificate.
+private_key = $dir/private/ca.key.pem
+certificate = $dir/certs/ca.cert.pem
+
+# For certificate revocation lists.
+crlnumber = $dir/crlnumber
+crl = $dir/crl/ca.crl.pem
+crl_extensions = crl_ext
+default_crl_days = 30
+
+# SHA-1 is deprecated, so use SHA-2 instead.
+default_md = sha256
+
+name_opt = ca_default
+cert_opt = ca_default
+default_days = 375
+preserve = no
+policy = policy_strict
+
+[ policy_strict ]
+# The root CA should only sign intermediate certificates that match.
+# See the POLICY FORMAT section of `man ca`.
+countryName = match
+stateOrProvinceName = match
+organizationName = match
+organizationalUnitName = optional
+commonName = supplied
+emailAddress = optional
+
+[ policy_loose ]
+# Allow the intermediate CA to sign a more diverse range of certificates.
+# See the POLICY FORMAT section of the `ca` man page.
+countryName = optional
+stateOrProvinceName = optional
+localityName = optional
+organizationName = optional
+organizationalUnitName = optional
+commonName = supplied
+emailAddress = optional
+
+[ req ]
+# Options for the `req` tool (`man req`).
+default_bits = 2048
+distinguished_name = req_distinguished_name
+string_mask = utf8only
+
+# SHA-1 is deprecated, so use SHA-2 instead.
+default_md = sha256
+
+# Extension to add when the -x509 option is used.
+x509_extensions = v3_ca
+
+[ req_distinguished_name ]
+# See <https://en.wikipedia.org/wiki/Certificate_signing_request>.
+countryName = Country Name (2 letter code)
+stateOrProvinceName = State or Province Name
+localityName = Locality Name
+0.organizationName = Organization Name
+organizationalUnitName = Organizational Unit Name
+commonName = Common Name
+emailAddress = Email Address
+
+# Optionally, specify some defaults.
+countryName_default = US
+stateOrProvinceName_default = California
+localityName_default = Palo Alto
+0.organizationName_default = My company
+organizationalUnitName_default = IT
+emailAddress_default =
+
+[ v3_ca ]
+# Extensions for a typical CA (`man x509v3_config`).
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always,issuer
+basicConstraints = critical, CA:true
+keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+
+[ v3_intermediate_ca ]
+# Extensions for a typical intermediate CA (`man x509v3_config`).
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always,issuer
+basicConstraints = critical, CA:true, pathlen:0
+keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+
+[ usr_cert ]
+# Extensions for client certificates (`man x509v3_config`).
+basicConstraints = CA:FALSE
+nsCertType = client, email
+nsComment = "OpenSSL Generated Client Certificate"
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer
+keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
+extendedKeyUsage = clientAuth, emailProtection
+
+[ server_cert ]
+# Extensions for server certificates (`man x509v3_config`).
+basicConstraints = CA:FALSE
+nsCertType = server
+nsComment = "OpenSSL Generated Server Certificate"
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer:always
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+
+[ crl_ext ]
+# Extension for CRLs (`man x509v3_config`).
+authorityKeyIdentifier=keyid:always
+
+[ ocsp ]
+# Extension for OCSP signing certificates (`man ocsp`).
+basicConstraints = CA:FALSE
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer
+keyUsage = critical, digitalSignature
+extendedKeyUsage = critical, OCSPSigning
\ No newline at end of file
diff --git a/site/docs/latest/security/tls-transport.md
b/site/docs/latest/security/tls-transport.md
new file mode 100644
index 0000000000..1aeff3f66f
--- /dev/null
+++ b/site/docs/latest/security/tls-transport.md
@@ -0,0 +1,209 @@
+---
+title: Transport Encryption using TLS
+---
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## TLS Overview
+
+By default, Apache Pulsar clients communicate with the Apache Pulsar service
in plain text, which means that all data is sent in the clear. TLS can be used
to encrypt this traffic so that it cannot be snooped by a man-in-the-middle
attacker.
+
+TLS can be configured for both encryption and authentication. You may
configure just TLS transport encryption, which is covered in this guide. TLS
authentication is covered [elsewhere](../tls). Alternatively, you can use
[another authentication mechanism](../athenz) on top of TLS transport
encryption.
+
+> Note that enabling TLS may have a performance impact due to encryption
overhead.
+
+## TLS concepts
+
+TLS is a form of [public key
cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography).
Encryption is performed using key pairs consisting of a public key and a
private key. Messages are encrypted with the public key and can be decrypted
with the private key.
+
+To use TLS transport encryption, you need two kinds of key pairs, **server key
pairs** and a **certificate authority**.
+
+A third kind of key pair, **client key pairs**, are used for [client
authentication]("../tls").
+
+The **certificate authority** private key should be stored in a very secure
location (a fully encrypted, disconnected, air gapped computer). The
certificate authority public key, the **trust cert**, can be freely shared.
+
+For both client and server key pairs, the administrator first generates a
private key and a certificate request. Then the certificate authority private
key is used to sign the certificate request, generating 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 they are talking to has a key pair that was signed by the
certificate authority. A man-in-the-middle attacker would 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 was signed by the certificate authority. The Common
Name of the **client cert** is then used as the client's role token (see
[Overview](../overview)).
+
+## Creating TLS Certificates
+
+Creating TLS certificates for Pulsar involves creating a [certificate
authority](#certificate-authority) (CA), [server
certificate](#server-certificate), and [client
certificate](#client-certificate).
+
+The following guide is an abridged guide to setting up a certificate
authority. For a more detailed guide, there are plenty of resource on the
internet. We recommend the [this
guide](https://jamielinux.com/docs/openssl-certificate-authority/index.html).
+
+### Certificate authority
+
+The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others. The CA should be stored in a very secure location
(ideally completely disconnected from networks, air gapped, and fully
encrypted).
+
+Create a directory for your CA, and place [this openssl configuration
file](../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 directories needed for the CA.
+
+```bash
+$ mkdir my-ca
+$ cd my-ca
+$ wget {{ "/docs/latest/security/openssl.cnf" | absolute_url }}
+$ export CA_HOME=$(pwd)
+```
+
+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
+```
+
+After answering the question prompts, this will store CA-related files in the
`./my-ca` directory. Within that directory:
+
+* `certs/ca.cert.pem` is the public certificate. It is meant to be distributed
to all parties involved.
+* `private/ca.key.pem` is the private key. This is only needed when signing a
new certificate for either broker or clients and it must be safely guarded.
+
+### Server certificate
+
+Once a CA certificate has been created, you can create certificate requests
and sign them with the CA.
+
+The following commands will ask you a few questions and then create the
certificates. When asked for the common name, you should match the hostname of
the broker. You could also use a wildcard to match a group of broker hostnames,
for example `*.broker.usw.example.com`. This ensures that the same certificate
can be reused on multiple machines.
+
+{% include admonition.html type="info" content="Sometimes it is not possible
or makes no sense to match the hostname, such as when the brokers are created
with random hostnames, or you plan to connect to the hosts via their IP. In
this case, the client should be configured to disable TLS hostname
verification." %}
+
+First 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 convert it.
+
+```bash
+$ openssl pkcs8 -topk8 -inform PEM -outform PEM \
+ -in broker.key.pem -out broker.key-pk8.pem -nocrypt
+```
+
+Generate the certificate request...
+
+```bash
+$ openssl req -config openssl.cnf \
+ -key broker.key.pem -new -sha256 -out broker.cert.pem
+```
+
+... and sign it with the certificate authority.
+```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 can be used along with `ca.cert.pem` to configure
TLS transport encryption for your broker and proxy nodes.
+
+## Broker Configuration
+
+To configure a Pulsar {% popover broker %} to use TLS transport encryption,
you'll need to make some changes to `broker.conf`, which is located in the
`conf` directory of your [Pulsar
installation](../../getting-started/LocalCluster).
+
+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
+```
+
+{% include message.html id="broker_conf_doc" %}
+
+# Proxy Configuration
+
+Proxies need to configure TLS in two directions, for clients connecting to the
proxy, and for the proxy to be able to connect to brokers.
+
+```properties
+# 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 TLS transport encryption is enabled, you need to configure the client to
use ```https://``` and port 8443 for the web service URL, and
```pulsar+ssl://``` and port 6651 for the broker service URL.
+
+As the server certificate you generated above doesn't 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.
+
+### CLI tools
+
+[Command-line tools](../../reference/CliTools) like
[`pulsar-admin`](../../reference/CliTools#pulsar-admin),
[`pulsar-perf`](../../reference/CliTools#pulsar-perf), and
[`pulsar-client`](../../reference/CliTools#pulsar-client) use the
`conf/client.conf` config file in a Pulsar installation.
+
+You'll need to add the following parameters to that file to use TLS transport
with Pulsar's CLI tools:
+
+```properties
+webServiceUrl=https://broker.example.com:8443/
+brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
+useTls=true
+tlsAllowInsecureConnection=false
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+```
+
+### 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")
+ .build();
+```
+
+### Python client
+
+```python
+from pulsar import Client
+
+client = Client("pulsar+ssl://broker.example.com:6651/",
+ tls_trust_certs_file_path="/path/to/ca.cert.pem",
+ tls_allow_insecure_connection=False)
+```
+
+### C++ client
+
+```c++
+#include <pulsar/Client.h>
+
+pulsar::ClientConfiguration config;
+config.setUseTls(true);
+config.setTlsTrustCertsFilePath("/path/to/ca.cert.pem");
+config.setTlsAllowInsecureConnection(false);
+
+pulsar::Client client("pulsar+ssl://broker.example.com:6651/", config);
+```
diff --git a/site/docs/latest/security/tls.md b/site/docs/latest/security/tls.md
index f343eeeb9c..acacab2740 100644
--- a/site/docs/latest/security/tls.md
+++ b/site/docs/latest/security/tls.md
@@ -1,5 +1,5 @@
---
-title: Encryption and Authentication using TLS
+title: Authentication using TLS
---
<!--
@@ -23,139 +23,133 @@ title: Encryption and Authentication using TLS
-->
-## TLS Overview
+## TLS Authentication Overview
-With [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security)
authentication, the server authenticates the client (also called “2-way
authentication”).
-Since TLS authentication requires TLS encryption, this page shows you how to
configure both at the same time.
+TLS authentication is an extension of [TLS transport
encryption](../tls-transport), but instead of only servers having keys and
certs which the client uses the verify the server's identity, clients also have
keys and certs which the server uses to verify the client's identity. 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.
-By default, Apache Pulsar communicates in plain text service url, which means
that all data is sent in the clear.
-To encrypt communication, it is recommended to configure all the Apache Pulsar
components in your deployment to use TLS encryption.
+### Creating client certificates
-TLS can be configured for encryption or authentication. You may configure just
TLS encryption
-(by default TLS encryption includes certificate authentication of the server)
and independently choose a separate mechanism
-for client authentication, e.g. TLS, [Athenz](../athenz), etc. Note that TLS
encryption, technically speaking, already enables
-1-way authentication in which the client authenticates the server certificate.
So when referring to TLS authentication, it is really
-referring to 2-way authentication in which the broker also authenticates the
client certificate.
+Client certificates are generated using the same certificate authority as was
used to generate the server certificates.
-> Note that enabling TLS may have a performance impact due to encryption
overhead.
+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 will be authenticated as.
-## Creating TLS Certificates
-
-Creating TLS certificates for Pulsar involves creating a [certificate
authority](#certificate-authority) (CA), [broker
certificate](#broker-certificate), and [client
certificate](#client-certificate).
+First generate the key.
+```bash
+$ openssl genrsa -out admin.key.pem 2048
+```
-### Certificate authority
+Similar to the broker, the client expects the key to be in [PKCS
8](https://en.wikipedia.org/wiki/PKCS_8) format, so convert it.
-The first step is to create the certificate for the CA. The CA will be used to
sign both the broker and client certificates, in order to ensure that each
party will trust the others.
+```bash
+$ openssl pkcs8 -topk8 -inform PEM -outform PEM \
+ -in admin.key.pem -out admin.key-pk8.pem -nocrypt
+```
-#### Linux
+Generate the certificate request. When asked for a **common name**, enter the
**role token** which you want this key pair to authenticate a client as.
```bash
-$ CA.pl -newca
+$ openssl req -config openssl.cnf \
+ -key admin.key.pem -new -sha256 -out admin.cert.pem
```
-#### macOS
+Sign with request with the certificate authority. Note that that client certs
uses the **usr_cert** extension, which allows the cert to be used for client
authentication.
```bash
-$ /System/Library/OpenSSL/misc/CA.pl -newca
+$ openssl ca -config openssl.cnf -extensions usr_cert \
+ -days 1000 -notext -md sha256 \
+ -in admin.csr.pem -out admin.cert.pem
```
-After answering the question prompts, this will store CA-related files in the
`./demoCA` directory. Within that directory:
+This will give you a cert, `admin.cert.pem`, and a key, `admin.key-pk8.pem`,
which, with `ca.cert.pem`, can be used by clients to authenticate themselves to
brokers and proxies as the role token ``admin``.
-* `demoCA/cacert.pem` is the public certificate. It is meant to be distributed
to all parties involved.
-* `demoCA/private/cakey.pem` is the private key. This is only needed when
signing a new certificate for either broker or clients and it must be safely
guarded.
+## Enabling TLS Authentication ...
-### Broker certificate
+### ... on Brokers
-Once a CA certificate has been created, you can create certificate requests
and sign them with the CA.
+To configure brokers to authenticate clients, put the following in
`broker.conf`, alongside [the configuration to enable tls
transport](../tls-transport#broker-configuration):
-The following commands will ask you a few questions and then create the
certificates. When asked for the common name, you need to match the hostname of
the broker. You could also use a wildcard to match a group of broker hostnames,
for example `*.broker.usw.example.com`. This ensures that the same certificate
can be reused on multiple machines.
-
-```shell
-$ openssl req \
- -newkey rsa:2048 \
- -sha256 \
- -nodes \
- -out broker-cert.csr \
- -outform PEM
+```properties
+# Configuration to enable authentication
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
```
-Convert the key to [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format:
+### ... on Proxies
-```shell
-$ openssl pkcs8 \
- -topk8 \
- -inform PEM \
- -outform PEM \
- -in privkey.pem \
- -out broker-key.pem \
- -nocrypt
-```
-
-This will create two broker certificate files named `broker-cert.csr` and
`broker-key.pem`. Now you can create the signed certificate:
+To configure proxies to authenticate clients, put the folling in `proxy.conf`,
alongside [the configuration to enable tls
transport](../tls-transport#proxy-configuration):
-```shell
-$ openssl ca \
- -out broker-cert.pem \
- -infiles broker-cert.csr
-```
+The proxy should have its own client key pair for connecting to brokers. The
role token for this key pair should be configured in the ``proxyRoles`` of the
brokers. See the [authorization guide](../authorization) for more details.
-At this point, you should have a `broker-cert.pem` and `broker-key.pem` file.
These will be needed for the broker.
+```properties
+# For clients connecting to the proxy
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
-### Client certificate
+# 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
+```
-To create a client certificate, repeat the steps in the previous section, but
did create `client-cert.pem` and `client-key.pem` files instead.
+## Client configuration
-For the client common name, you need to use a string that you intend to use as
the [role token](../overview#role-tokens) for this client, though it doesn't
need to match the client hostname.
+When TLS authentication, the client needs to connect via TLS transport, so you
need to configure the client to use ```https://``` and port 8443 for the web
service URL, and ```pulsar+ssl://``` and port 6651 for the broker service URL.
-## Configure the broker for TLS
+### CLI tools
-To configure a Pulsar {% popover broker %} to use TLS authentication, you'll
need to make some changes to the `broker.conf` configuration file, which is
located in the `conf` directory of your [Pulsar
installation](../../getting-started/LocalCluster).
+[Command-line tools](../../reference/CliTools) like
[`pulsar-admin`](../../reference/CliTools#pulsar-admin),
[`pulsar-perf`](../../reference/CliTools#pulsar-perf), and
[`pulsar-client`](../../reference/CliTools#pulsar-client) use the
`conf/client.conf` config file in a Pulsar installation.
-Add these values to the configuration file (substituting the appropriate
certificate paths where necessary):
+You'll need to add the following parameters to that file to use TLS
authentication with Pulsar's CLI tools:
```properties
-# Enable TLS and point the broker to the right certs
-tlsEnabled=true
-tlsCertificateFilePath=/path/to/broker-cert.pem
-tlsKeyFilePath=/path/to/broker-key.pem
-tlsTrustCertsFilePath=/path/to/cacert.pem
-
-# Enable the TLS auth provider
-authenticationEnabled=true
-authorizationEnabled=true
-authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
+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
```
-{% include message.html id="broker_conf_doc" %}
+### Java client
-## Configure the discovery service
+```java
+import org.apache.pulsar.client.api.PulsarClient;
-The {% popover discovery %} service used by Pulsar brokers needs to redirect
all HTTPS requests, which means that it needs to be trusted by the client as
well. Add this configuration in `conf/discovery.conf` in your Pulsar
installation:
-
-```properties
-tlsEnabled=true
-tlsCertificateFilePath=/path/to/broker-cert.pem
-tlsKeyFilePath=/path/to/broker-key.pem
+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();
```
-## Configure clients
+### Python client
-For more information on Pulsar client authentication using TLS, see the
following language-specific docs:
+```python
+from pulsar import Client, AuthenticationTLS
-* [Java client](../../clients/Java)
-* [C++ client](../../clients/Cpp)
+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)
+```
-## Configure CLI tools
+### C++ client
-[Command-line tools](../../reference/CliTools) like
[`pulsar-admin`](../../reference/CliTools#pulsar-admin),
[`pulsar-perf`](../../reference/CliTools#pulsar-perf), and
[`pulsar-client`](../../reference/CliTools#pulsar-client) use the
`conf/client.conf` config file in a Pulsar installation.
+```c++
+#include <pulsar/Client.h>
-You'll need to add the following authentication parameters to that file to use
TLS with Pulsar's CLI tools:
+pulsar::ClientConfiguration config;
+config.setUseTls(true);
+config.setTlsTrustCertsFilePath("/path/to/ca.cert.pem");
+config.setTlsAllowInsecureConnection(false);
-```properties
-serviceUrl=https://broker.example.com:8443/
-authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
-authParams=tlsCertFile:/path/to/client-cert.pem,tlsKeyFile:/path/to/client-key.pem
-useTls=true
-tlsAllowInsecureConnection=false
-tlsTrustCertsFilePath=/path/to/cacert.pem
+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);
```
+
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
