Authentication using Kerberos

Authentication using Kerberos

Kerberos 是一种网络身份验证协议。因其使用了秘钥加密，Kerberos 能为客户端与服务端上的各种应用程序提供强身份验证。

在 Pulsar 平台中，您可以选择使用 SASL 机制配合 Kerberos 实现身份验证。 Pulsar 使用了 Java 认证和授权服务（JASS）进行 SASL 的配置。因此，使用 Kerberos 身份验证前需要您配置 JAAS 。

本文详细介绍了如何在 Pulsar 客户端和 brokers （中介性代理）之间配置 Kerberos 与 SASL ，以及如何为 Pulsar 代理配置 Kerberos。

在客户端与 Broker 之间配置 Kerberos

先决条件

首先，您需要创建（或者已经拥有）一个密钥分发中心（KDC）。此外，您还需要提前配置和运行密钥分发中心（KDC）。

如果您的组织已经使用了 Kerberos 服务(例如 Active Directory )，那就不必为 Pulsar 安装新服务了。如果您的组织没有使用 Kerberos 服务，则需要安装一个 Kerberos 服务。您的 Linux 供应商可能提供了用于 Kerberos 的包。关于如何安装和配置 Kerberos，请参考 Ubuntu ，Redhat 。

注意，如果您使用 Oracle Java ，您需要下载对应您 Java 版本的 JCE 策略文件，并将它们复制到 $JAVA_HOME/jre/lib/security 目录。

Kerberos principals

若您要使用现有的 Kerberos 系统，请向 Kerberos 管理员索要集群中每个 broker 的 principal ，并使用 Kerberos 身份验证(通过客户机和工具)访问到 Pulsar 的每个操作系统用户的 principal 。

如果您已经安装了自己的 Kerberos 系统，那么可以使用以下命令创建这些 principals :

### 为 broker 添加 Principals 
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}"
### 为客户端添加 Principals 
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.

Broker principal 的第一部分（例如， broker/{hostname}@{REALM} 中的 broker ）是每个主机的 serverType 。 serverType 建议值为 broker (主机运行 Pulsar broker 服务)和 proxy (主机运行 Pulsar proxy 服务)。

配置如何连接到 KDC

您需要输入下面的命令来为客户端和 Broker 端指定 krb5.conf 文件的路径。 krb5.conf 文件的内容说明了默认的 Realm 和 KDC 信息。 See JDK’s Kerberos Requirements for more details.

-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 配置文件

客户端和 broker 端都需要 JAAS 配置文件。 JAAS 配置文件提供了用于连接 KDC 的信息（section）。 Here is an example named pulsar_jaas.conf:

 PulsarBroker {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab=true
   storeKey=true
   useTicketCache=false
   keyTab="/etc/security/keytabs/pulsarbroker.keytab"
   principal="broker/localhost@EXAMPLE.COM";
};
 PulsarClient {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab=true
   storeKey=true
   useTicketCache=false
   keyTab="/etc/security/keytabs/pulsarclient.keytab"
   principal="client/localhost@EXAMPLE.COM";
};

You need to set the JAAS configuration file path as JVM parameter for client and broker. 例如:

    -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf

In the pulsar_jaas.conf file above

PulsarBroker 是 JAAS 文件中一种每个 Broker 都会使用的组名（ section name ）。此组会告知 Broker 要去使用 Kerberos 中的哪个 principal 并存储了 principal 的 keytab 位置信息。 PulsarBroker 允许 Broker 使用本组中指定的 keytab。
PulsarClient 是 JAAS 文件中一种每个 Broker 都会使用的组名（ section name ）。此组会告知 client要去使用 Kerberos 中的哪个 principal 并存储了 principal 的 keytab 位置信息。 PulsarClient 允许 client使用本组中指定的 keytab。下面的示例在 Pulsar 内部管理配置和 bin/pulsar-client 、 bin/pulsar-perf 与 bin/pulsar-admin 的 CLI （命令行）指令中也都重用了这个 PulsarClient 部分。您还可以为不同的用例添加单独的组。

您可以有两个独立的 JAAS 配置文件：

包含 PulsarBroker 和 PulsarClient 两个部分的 broker 文件；
仅有 PulsarClient 部分的客户端文件。

关于 Brokers 的 Kerberos 配置

配置 `broker.conf` 文件

在 broker.conf 文件中设置 Kerberos 相关配置。

Set authenticationEnabled to true;
Set authenticationProviders to choose AuthenticationProviderSasl;
设置 saslJaasClientAllowedIds 正则表达式，用于 principal 的 broker 连接许可；
设置 saslJaasBrokerSectionName ，对应于 broker JAAS 配置文件中的组名；

要使 Pulsar 内部管理客户端正常工作，您需要在 broker.conf 文件中配置如下：

为客户端插件 AuthenticationSasl 设置 brokerClientAuthenticationPlugin ；
将 JSON 字符串中的值 {"saslJaasClientSectionName":"PulsarClient"， "serverType":"broker"} 设置给 brokerClientAuthenticationParameters ，其中 PulsarClient 是 pulsar_jaas.conf 文件中的组名。 "serverType":"broker" 表示内部管理客户端连接到 Pulsar broker ；

Here is an example:

authenticationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
saslJaasClientAllowedIds=.*client.*
saslJaasBrokerSectionName=PulsarBroker
## broker 代理自身的身份验证设置。 当 broker 连接到其他 broker 时使用
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}

设置 Broker JVM 参数

使用附加选项设置 JAAS 配置文件和 krb5 配置文件的 JVM 参数。

   -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

您必须确保启动 broker 的操作系统用户能够访问 pulsar_jaas.conf 文件中配置的 keytab 和 krb5.conf 文件中配置的 kdc 服务器。

客户端的 Kerberos 配置

Java 客户端和 Java 管理客户端

在客户端应用程序的项目依赖项中包含 pular -client-auth-sasl 。

    <dependency>
      <groupId>org.apache.pulsar</groupId>
      <artifactId>pulsar-client-auth-sasl</artifactId>
      <version>${pulsar.version}</version>
    </dependency>

使用 AuthenticationSasl 配置验证类型，并为其提供验证参数。

您需要两个参数：

saslJaasClientSectionName 。该参数对应客户端的 JAAS 配置文件部分；
serverType 。这个参数表示此客户端连接的是 broker 还是 proxy （透传性代理）。客户端使用该参数获知它应该使用哪一个服务器端的 principal 。

当您使用上述 JAAS 配置文件中的设置在客户端和 broker 之间进行身份验证时，我们需要将 saslJaasClientSectionName 设置为 PulsarClient ，并将 serverType 设置为 broker 。

The following is an example of creating a Java client:

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.

authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
authParams={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}

步骤 2 。输入下面的命令为 JAAS 配置文件和 krb5 配置文件设置 JVM 参数，并提供其他选项。

   -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf

您可以在 pulsar_tools_env.sh 文件中 PULSAR_EXTRA_OPTS 的末尾添加这个，或者直接在 CLI 工具脚本中添加一行 OPTS="$OPTS -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf " 。

配置的含义与 Java 客户端部分中的配置含义相同。

用于处理 Pulsar Proxy 的 Kerberos 配置

通过上述配置，客户端和 broker 可以使用 Kerberos 进行身份验证。

连接到 Pulsar Proxy 的客户端有些不同。 Pulsar Proxy (作为 Kerberos 中的 SASL 服务器)首先验证客户端(作为 Kerberos 中的 SASL 客户端); 然后 Pulsar broker 验证 Pulsar Proxy 。

现在，通过对比上述客户端和 broker 之间的配置，我们将向您展示如何配置 Pulsar Proxy 。

在 Kerberos 中创建 Pulsar Proxy 的 principal

与以上配置相比，需要为 Pulsar Proxy 添加新的 principals 。如果您已经有了客户端和 broker 的 principal ，那么您只需要在这里添加 proxy principal 。

### 添加 Pulsar Proxy 的 Principals 
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}"
### 添加 broker 的 Principals 
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}"
### 添加客户端的 Principals 
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}"

在 Pulsar Proxy 的 JAAS 配置文件中添加组

与上述配置相比较，在 JAAS 配置文件中为 Pulsar Proxy 增加新组。

Here is an example named pulsar_jaas.conf:

 PulsarBroker {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab=true
   storeKey=true
   useTicketCache=false
   keyTab="/etc/security/keytabs/pulsarbroker.keytab"
   principal="broker/localhost@EXAMPLE.COM";
};
 PulsarProxy {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab=true
   storeKey=true
   useTicketCache=false
   keyTab="/etc/security/keytabs/pulsarproxy.keytab"
   principal="proxy/localhost@EXAMPLE.COM";
};
 PulsarClient {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab=true
   storeKey=true
   useTicketCache=false
   keyTab="/etc/security/keytabs/pulsarclient.keytab"
   principal="client/localhost@EXAMPLE.COM";
};

Proxy 客户端配置

Pulsar 客户端配置与客户端和 broker 配置类似，除了您需要将 serverType 设置为 proxy 而不是 broker ，因为您需要在客户端和 proxy 之间进行 Kerberos 身份验证。

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:

## related to authenticate client.
authenticationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
saslJaasClientAllowedIds=.*client.*
saslJaasBrokerSectionName=PulsarProxy
## 与 broker 身份验证相关的
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarProxy", "serverType":"broker"}
forwardAuthorizationCredentials=true

第一部分涉及到客户端与 Pulsar Proxy 之间的身份验证。 In this phase, client works as SASL client, while Pulsar Proxy works as SASL server.

第二部分是 Pulsar Proxy 和 Pulsar Broker 之间的验证。 In this phase, Pulsar Proxy works as SASL client, while Pulsar Broker works as SASL server.

Broker 侧配置

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

关于授权和角色令牌（role token）

对于 Kerberos 身份验证，我们通常使用经过身份验证的 principal 作为用于 Pulsar 授权的角色令牌。 For more information of authorization in Pulsar, see security authorization.

如果你启用了’authorizationEnabled’，你需要在 broker.conf 中设置 superUserRoles 对应于 kdc 中注册的名称。

例如:

superUserRoles=client/{clientIp}@EXAMPLE.COM

关于 ZooKeeper 服务和 Broker 之间的身份验证

当您使用 Zookeeper 进行身份验证时， Pulsar Broker 充当 Kerberos 客户端。根据 ZooKeeper文档，你需要在 conf/ ZooKeeper.conf 中设置：

authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
requireClientAuthScheme=sasl

输入以下命令，在 Pulsar Broker 使用的文件 pulsar_jaas.conf 中添加一段 `Client 配置。

 Client {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab=true
   storeKey=true
   useTicketCache=false
   keyTab="/etc/security/keytabs/pulsarbroker.keytab"
   principal="broker/localhost@EXAMPLE.COM";
};
`
```
``
在使用 ZooKeeper 进行身份验证时，此设置中的 Pulsar Broker 和 keyTab 文件的 principal 指示了 Broker 的角色。
## 关于 BookKeeper 储存系统和 Broker 之间的身份验证
当您使用 Bookie 进行身份验证时，Pulsar Broker 充当 Kerberos 客户端。 根据 [BookKeeper文档](http://bookkeeper.apache.org/docs/latest/security/sasl/) ，需要在 `broker.conf` 中添加 `bookkeeperClientAuthenticationPlugin` 参数：
```
bookkeeperClientAuthenticationPlugin=org.apache.bookkeeper.sasl.SASLClientProviderFactory
```
在此设置中， `SASLClientProviderFactory` 在 Broker 中创建了一个 BookKeeper SASL 客户端， Broker 通过 Bookie 节点使用创建的 SASL 客户端进行身份验证。
输入以下命令，在 Pulsar Broker 使用的 `pulsar_jaas.conf` 文件中添加一段 `BookKeeper` 配置：
```
 BookKeeper {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab=true
   storeKey=true
   useTicketCache=false
   keyTab="/etc/security/keytabs/pulsarbroker.keytab"
   principal="broker/localhost@EXAMPLE.COM";
};
```
在使用 Bookie 进行身份验证时，此设置中的 Pulsar Broker 和 keyTab 文件的 principal 指示了 Broker 的角色。
``

Authentication using Kerberos

Authentication using Kerberos

在客户端与 Broker 之间配置 Kerberos

先决条件

Kerberos principals

配置如何连接到 KDC

JAAS 配置文件

关于 Brokers 的 Kerberos 配置

配置 broker.conf 文件

设置 Broker JVM 参数

客户端的 Kerberos 配置

Java 客户端和 Java 管理客户端

Configure CLI tools

用于处理 Pulsar Proxy 的 Kerberos 配置

在 Kerberos 中创建 Pulsar Proxy 的 principal

在 Pulsar Proxy 的 JAAS 配置文件中添加组

Proxy 客户端配置

Kerberos configuration for Pulsar proxy service

Broker 侧配置

关于授权和角色令牌（role token）

关于 ZooKeeper 服务和 Broker 之间的身份验证

配置 `broker.conf` 文件