This is an automated email from the ASF dual-hosted git repository.
sijie 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 b8aa2c9 [doc] Improve Pulsar Security Kerberos (#5069)
b8aa2c9 is described below
commit b8aa2c9e6e6e9e76a1b724c8e23b6c6965a0d1aa
Author: Monica-zy <[email protected]>
AuthorDate: Tue Sep 3 02:31:49 2019 +0800
[doc] Improve Pulsar Security Kerberos (#5069)
### Motivation
Improve the language and the overall descriptive style of the Pulsar
Security document ( Security-kerberos section):
http://pulsar.apache.org/docs/en/next/security-kerberos/
### Modifications
Adjust the tone, personal pronouns, voice also some typo errors of some
sentences in the document.
---
site2/docs/security-kerberos.md | 107 +++++++++++++++++++---------------------
1 file changed, 51 insertions(+), 56 deletions(-)
diff --git a/site2/docs/security-kerberos.md b/site2/docs/security-kerberos.md
index 9c3b038..11e3aa9 100644
--- a/site2/docs/security-kerberos.md
+++ b/site2/docs/security-kerberos.md
@@ -4,26 +4,26 @@ title: Authentication using Kerberos
sidebar_label: Authentication using Kerberos
---
-[Kerberos](https://web.mit.edu/kerberos/) is a network authentication
protocol. It is designed to provide strong authentication for client/server
applications by using secret-key cryptography.
+[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, we 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 must provide JAAS configurations for Kerberos
authentication.
+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.
-In this document, we will introduce how to configure `Kerberos` with `SASL`
between Pulsar clients and brokers in detail, and then how to configure
Kerberos for Pulsar proxy.
+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) configured
and running.
+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 is already using a Kerberos server (for example, by using
`Active Directory`), there is no need to install a new server for Pulsar.
Otherwise you will need to install one. Your Linux vendor likely has packages
for `Kerberos` and a short guide on how to install and configure it:
([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)).
+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 are using Oracle Java, you need to download JCE policy files
for your Java version and copy them to the `$JAVA_HOME/jre/lib/security`
directory.
+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
+#### Kerberos principals
-If you are using existing Kerberos system, ask your Kerberos administrator for
a principal for each Brokers in your cluster and for every operating system
user that will access Pulsar with Kerberos authentication(via clients and
tools).
+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:
@@ -36,14 +36,13 @@ 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 it is a *Kerberos* requirement that all your hosts can be resolved
with their FQDNs.
+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).
+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 specify the path to the `krb5.conf` file for both client and
broker side. The contents of `krb5.conf` file indicate 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.
+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
@@ -66,7 +65,7 @@ Usually machines configured with kerberos already have a
system wide configurati
#### JAAS configuration file
-JAAS configuration file is needed for both client and broker sides. It
provides the section of information that used to connect KDC. Here is an
example named `pulsar_jaas.conf`:
+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 {
@@ -96,31 +95,29 @@ You need to set the `JAAS` configuration file path as JVM
parameter for client a
In the `pulsar_jaas.conf` file above
-1. `PulsarBroker` is a section name in the JAAS file used by each broker. This
section tells the broker which principal to use inside Kerberos
- and the location of the keytab where the principal is stored. It allows
the broker to use the keytab specified in this section.
-2. `PulsarClient` is a section name in the JASS file used by each client. This
section tells the client which principal to use inside Kerberos
- and the location of the keytab where the principal is stored. It allows
the client to use the keytab specified in this section.
- In the following example, this `PulsarClient` section will also be reused
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.
+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 has sections of both `PulsarBroker` and
`PulsarClient`;
-* the file for a client only has a `PulsarClient` section.
+* 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 `broker.conf` file
+#### 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 corresponding to the section in JAAS
configuration file for 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 above `pulsar_jaas.conf` file, and
`"serverType":"broker"` indicate that internal admin client will connect to a
Pulsar Broker;
+ - 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:
@@ -143,8 +140,7 @@
brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarClient"
```
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)
-Make sure that the keytabs configured in the `pulsar_jaas.conf` file and kdc
server in the `krb5.conf` file are reachable by the operating system user who
is starting broker.
-
+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
@@ -160,13 +156,13 @@ In client application, include `pulsar-client-auth-sasl`
in your project depende
</dependency>
```
-configure the authentication type to use `AuthenticationSasl`, and also
provide the authentication parameters to it.
+Configure the authentication type to use `AuthenticationSasl`, and also
provide the authentication parameters to it.
-There are 2 parameters needed:
-- `saslJaasClientSectionName` is corresponding to the section in JAAS
configuration file for client;
-- `serverType` stands for whether this client is connect to broker or proxy,
and client use this parameter to know which server side principal should be
used.
+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 authenticate between client and broker with the setting in above JAAS
configuration file, we need to set `saslJaasClientSectionName` to
`PulsarClient` and `serverType` to `broker`.
+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:
@@ -187,26 +183,26 @@ The following is an example of creating a Java client:
.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
running the application like below:
+> 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
```
-Make sure that the keytabs configured in the `pulsar_jaas.conf` file and kdc
server in the `krb5.conf` file are reachable by the operating system user who
is starting pulsar client.
+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 are using a command-line tool (such as `bin/pulsar-client`,
`bin/pulsar-perf` and `bin/pulsar-admin`), you need to preform the following
steps:
+If you use a command-line tool (such as `bin/pulsar-client`, `bin/pulsar-perf`
and `bin/pulsar-admin`), you need to preform the following steps:
-Step 1. Config your `client.conf`.
+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. Set JVM parameters for JAAS configuration file and krb5 configuration
file with additional options.
+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
```
@@ -214,19 +210,19 @@ Step 2. Set JVM parameters for JAAS configuration file
and krb5 configuration fi
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 that in Java client section.
+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.
-If a client wants to connect to Pulsar Proxy, it is a little different. Client
(as a SASL client in Kerberos) will be authenticated by Pulsar Proxy (as a SASL
Server in Kerberos) first; and then Pulsar Proxy will be authenticated by
Pulsar broker.
+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 comparing with the above configuration between client and broker, we will
show how to configure Pulsar Proxy.
+Now in comparision 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
-Comparing with the above configuration, you need to add new principal for
Pulsar Proxy. If you already have principals for client and broker, only add
proxy principal here.
+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
@@ -242,7 +238,7 @@ sudo /usr/sbin/kadmin.local -q "ktadd -k
/etc/security/keytabs/{client-keytabnam
### Add a section in JAAS configuration file for Pulsar Proxy
-Comparing with the above configuration, add a new section for Pulsar Proxy in
JAAS configuration file.
+In comparision with the above configuration, add a new section for Pulsar
Proxy in JAAS configuration file.
Here is an example named `pulsar_jaas.conf`:
@@ -275,9 +271,9 @@ Here is an example named `pulsar_jaas.conf`:
};
```
-### Proxy Client configuration
+### Proxy client configuration
-Pulsar client configuration is similar with client and broker configuration,
except that `serverType` is set to `proxy` instead of `broker`, because it
needs to do Kerberos authentication between client and proxy.
+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");
@@ -296,13 +292,13 @@ Pulsar client configuration is similar with client and
broker configuration, exc
.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
running the application like below:
+> 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
+### Kerberos configuration for Pulsar proxy service
In the `proxy.conf` file, set Kerberos related configuration. Here is an
example:
```shell
@@ -318,9 +314,9 @@
brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarProxy",
forwardAuthorizationCredentials=true
```
-The first part is related to authenticate between client and Pulsar Proxy. In
this phase, client works as SASL client, while Pulsar Proxy works as SASL
server.
+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 is related to authenticate between Pulsar Proxy and Pulsar
Broker. In this phase, Pulsar Proxy works as SASL client, while Pulsar Broker
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.
@@ -335,9 +331,9 @@ saslJaasBrokerSectionName=PulsarBroker
## Regarding authorization and role token
-For Kerberos authentication, the authenticated principal is used as the role
token for Pulsar authorization. For more information of authorization in
Pulsar, see [security authorization](security-authorization.md).
+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.md).
-If you enabled authorizationEnabled you need set `superUserRoles` in
`broker.conf` that corresponding to the name registered in kdc
+If you enable 'authorizationEnabled', you need to set `superUserRoles` in
`broker.conf` that corresponds to the name registered in kdc.
For example:
```bash
@@ -346,14 +342,14 @@ superUserRoles=client/{clientIp}@EXAMPLE.COM
## Regarding authentication between ZooKeeper and Broker
-Pulsar Broker acts as a Kerberos client when authenticating 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`:
+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
```
-And add a section of `Client` configurations in the file `pulsar_jaas.conf`,
which is used by Pulsar Broker:
+Enter the following commands to add a section of `Client` configurations in
the file `pulsar_jaas.conf`, which Pulsar Broker uses:
```
Client {
@@ -366,11 +362,11 @@ And add a section of `Client` configurations in the file
`pulsar_jaas.conf`, whi
};
```
-In this setting, Pulsar Broker's principal and keyTab file indicates Broker's
role when authenticating with ZooKeeper.
+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 authenticating with Bookie.
According to [BookKeeper
document](http://bookkeeper.apache.org/docs/latest/security/sasl/), you need to
add `bookkeeperClientAuthenticationPlugin` parameter in `broker.conf`:
+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
@@ -378,7 +374,7 @@
bookkeeperClientAuthenticationPlugin=org.apache.bookkeeper.sasl.SASLClientProvid
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.
-And add a section of `BookKeeper` configurations in the `pulsar_jaas.conf`
that used by Pulsar Broker:
+Enter the following commands to add a section of `BookKeeper` configurations
in the `pulsar_jaas.conf` that Pulsar Broker uses:
```
BookKeeper {
@@ -391,5 +387,4 @@ And add a section of `BookKeeper` configurations in the
`pulsar_jaas.conf` that
};
```
-In this setting, Pulsar Broker's principal and keyTab file indicates Broker's
role when authenticating with Bookie.
-
+In this setting, the principal of Pulsar Broker and keyTab file indicates the
role of Broker when you authenticate with Bookie.
