Authentication using Kerberos

Kerberos is a network authentication protocol. It is designed to provide strong authentication for client/server applications by using secret-key cryptography.

In Pulsar, we use Kerberos with SASL as a choice for authentication. And Pulsar uses the Java Authentication and Authorization Service (JAAS) for SASL configuration. You must 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.

Configuration for Kerberos between Client and Broker

Prerequisites

To begin, you need to set up(or already have) a Key Distribution Center(KDC) configured and running.

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,Redhat).

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.

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 have installed your own Kerberos system, you can create these principals with the following commands:

  1. ### add Principals for broker
  2. sudo /usr/sbin/kadmin.local -q 'addprinc -randkey broker/{hostname}@{REALM}'
  3. sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{broker-keytabname}.keytab broker/{hostname}@{REALM}"
  4. ### add Principals for client
  5. sudo /usr/sbin/kadmin.local -q 'addprinc -randkey client/{hostname}@{REALM}'
  6. 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.

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 for more details.

  1. -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:

  1. [libdefaults]
  2.  default_realm = EXAMPLE.COM
  4. [realms]
  5.  EXAMPLE.COM  = {
  6.   kdc = localhost:62037
  7.  }

Usually machines configured with kerberos already have a system wide configuration and this configuration is optional.

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:

  1.  PulsarBroker {
  2.    com.sun.security.auth.module.Krb5LoginModule required
  3.    useKeyTab=true
  4.    storeKey=true
  5.    useTicketCache=false
  6.    keyTab="/etc/security/keytabs/pulsarbroker.keytab"
  7.    principal="broker/localhost@EXAMPLE.COM";
  8. };
  10.  PulsarClient {
  11.    com.sun.security.auth.module.Krb5LoginModule required
  12.    useKeyTab=true
  13.    storeKey=true
  14.    useTicketCache=false
  15.    keyTab="/etc/security/keytabs/pulsarclient.keytab"
  16.    principal="client/localhost@EXAMPLE.COM";
  17. };

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

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

In the pulsar_jaas.conf file above

  • PulsarBroker is a section name in the JAAS file used by each broker. This section tells the broker which principal to use inside Kerberosand the location of the keytab where the principal is stored. It allows the broker to use the keytab specified in this section.
  • PulsarClient is a section name in the JASS file used by each client. This section tells the client which principal to use inside Kerberosand the location of the keytab where the principal is stored. It allows the client to use the keytab specified in this section.It is also a choice to have 2 separate JAAS configuration files: the file for broker will only have PulsarBroker section; while the one for client only have PulsarClient section.

Kerberos configuration for Brokers

  • In the broker.conf file, set Kerberos related configuration.
  • 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.Here is an example:
  1. authenticationEnabled=true
  2. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
  3. saslJaasClientAllowedIds=.*client.*
  4. saslJaasBrokerSectionName=PulsarBroker
  • Set JVM parameter for JAAS configuration file and krb5 configuration file with additional option.
  1.    -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

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.

Kerberos configuration for clients

In client application, include pulsar-client-auth-sasl in your project dependency.

  1.     <dependency>
  2.       <groupId>org.apache.pulsar</groupId>
  3.       <artifactId>pulsar-client-auth-sasl</artifactId>
  4.       <version>${pulsar.version}</version>
  5.     </dependency>

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

The following is an example of creating a Java client:

  1. System.setProperty("java.security.auth.login.config", "/etc/pulsar/pulsar_jaas.conf");
  2. System.setProperty("java.security.krb5.conf", "/etc/pulsar/krb5.conf");
  4. Map<String, String> authParams = Maps.newHashMap();
  5. authParams.put("saslJaasClientSectionName", "PulsarClient");
  6. authParams.put("serverType", "broker");
  8. Authentication saslAuth = AuthenticationFactory
  9.         .create(org.apache.pulsar.client.impl.auth.AuthenticationSasl.class.getName(), authParams);
  11. PulsarClient client = PulsarClient.builder()
  12.         .serviceUrl("pulsar://my-broker.com:6650")
  13.         .authentication(saslAuth)
  14.         .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:

  1. 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.

If you are using command line, you can continue with these step:

  • Config your client.conf:
  1. authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
  2. authParams={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
  • Set JVM parameter for JAAS configuration file and krb5 configuration file with additional option.
  1.    -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

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.

Now comparing with the above configuration between client and broker, we will show how to configure Pulsar Proxy.

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.

  1. ### add Principals for Pulsar Proxy
  2. sudo /usr/sbin/kadmin.local -q 'addprinc -randkey proxy/{hostname}@{REALM}'
  3. sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{proxy-keytabname}.keytab proxy/{hostname}@{REALM}"
  4. ### add Principals for broker
  5. sudo /usr/sbin/kadmin.local -q 'addprinc -randkey broker/{hostname}@{REALM}'
  6. sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{broker-keytabname}.keytab broker/{hostname}@{REALM}"
  7. ### add Principals for client
  8. sudo /usr/sbin/kadmin.local -q 'addprinc -randkey client/{hostname}@{REALM}'
  9. 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

Comparing with the above configuration, add a new section for Pulsar Proxy in JAAS configuration file.

Here is an example named pulsar_jaas.conf:

  1.  PulsarBroker {
  2.    com.sun.security.auth.module.Krb5LoginModule required
  3.    useKeyTab=true
  4.    storeKey=true
  5.    useTicketCache=false
  6.    keyTab="/etc/security/keytabs/pulsarbroker.keytab"
  7.    principal="broker/localhost@EXAMPLE.COM";
  8. };
  10.  PulsarProxy {
  11.    com.sun.security.auth.module.Krb5LoginModule required
  12.    useKeyTab=true
  13.    storeKey=true
  14.    useTicketCache=false
  15.    keyTab="/etc/security/keytabs/pulsarproxy.keytab"
  16.    principal="proxy/localhost@EXAMPLE.COM";
  17. };
  19.  PulsarClient {
  20.    com.sun.security.auth.module.Krb5LoginModule required
  21.    useKeyTab=true
  22.    storeKey=true
  23.    useTicketCache=false
  24.    keyTab="/etc/security/keytabs/pulsarclient.keytab"
  25.    principal="client/localhost@EXAMPLE.COM";
  26. };

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.

  1. System.setProperty("java.security.auth.login.config", "/etc/pulsar/pulsar_jaas.conf");
  2. System.setProperty("java.security.krb5.conf", "/etc/pulsar/krb5.conf");
  4. Map<String, String> authParams = Maps.newHashMap();
  5. authParams.put("saslJaasClientSectionName", "PulsarClient");
  6. authParams.put("serverType", "proxy");        // ** here is the different **
  8. Authentication saslAuth = AuthenticationFactory
  9.         .create(org.apache.pulsar.client.impl.auth.AuthenticationSasl.class.getName(), authParams);
  11. PulsarClient client = PulsarClient.builder()
  12.         .serviceUrl("pulsar://my-broker.com:6650")
  13.         .authentication(saslAuth)
  14.         .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:

  1. 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:

  1. ## related to authenticate client.
  2. authenticationEnabled=true
  3. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
  4. saslJaasClientAllowedIds=.*client.*
  5. saslJaasBrokerSectionName=PulsarProxy
  7. ## related to be authenticated by broker
  8. brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
  9. brokerClientAuthenticationParameters=saslJaasClientSectionName:PulsarProxy,serverType:broker
  10. 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 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.

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.

  1. authenticationEnabled=true
  2. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
  3. saslJaasClientAllowedIds=.*client.*
  4. 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.

If you enabled authorizationEnabled you need set superUserRoles in broker.conf that corresponding to the name registered in kdc

For example:

  1. superUserRoles=client/{clientIp}@EXAMPLE.COM

Regarding authorization between BookKeeper and ZooKeeper

Adding bookkeeperClientAuthenticationPlugin parameter in broker.conf is a prerequisite for Broker (as a Kerberos client) being authenticated by Bookie (as a Kerberos Server):

  1. bookkeeperClientAuthenticationPlugin=org.apache.bookkeeper.sasl.SASLClientProviderFactory

For more details of how to configure Kerberos for BookKeeper and Zookeeper, refer to BookKeeper document.