Kerberos is a network authentication protocol designed to provide strong authentication for client applications and server applications by using secret-key cryptography.
In Pulsar, you can use Kerberos with SASL as a choice for authentication. Since Pulsar uses the Java Authentication and Authorization Service (JAAS) for SASL configuration, you need to provide JAAS configurations for Kerberos authentication.
:::note
Kerberos authentication uses the authenticated principal as the role token for Pulsar authorization. If you've enabled authorizationEnabled
, you need to set superUserRoles
in broker.conf
that corresponds to the name registered in KDC. For example:
superUserRoles=client/{clientIp}@EXAMPLE.COM
:::
Kerberos
. For how to install and configure Kerberos, see Ubuntu and Redhat.$JAVA_HOME/jre/lib/security
directory.To enable Kerberos authentication on brokers, complete the following steps.
If you use the existing Kerberos system, ask your Kerberos administrator to obtain a principal for each broker in your cluster and for every operating system user that accesses Pulsar with Kerberos authentication (via clients and CLI tools).
If you have installed your own Kerberos system, you need to create these principals with the following commands:
### add Principals for broker 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}" ### add Principals for client 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}"
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 Pulsar broker service) and proxy
(host machine runs Pulsar Proxy service).
Note that Kerberos requires that all your hosts can be resolved with their FQDNs.
In the broker.conf
file, set Kerberos-related configurations. Here is an example:
authenticationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl saslJaasClientAllowedIds=.*client.* ## regex for principals that are allowed to connect to brokers saslJaasServerSectionName=PulsarBroker ## corresponds to the section in the JAAS configuration file for brokers # Authentication settings of the broker itself. Used when the broker connects to other brokers, or when the proxy connects to brokers, either in same or other clusters brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
To make Pulsar internal admin client work properly, you need to:
brokerClientAuthenticationPlugin
to client plugin AuthenticationSasl
;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 broker.JAAS configuration file provides the information to connect KDC. 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"; };
In the above example:
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.PulsarClient
is a section name in the JASS file that each client uses. This section tells the client to use which principal inside Kerberos and the location of the keytab where the principal is stored.You need to set the pulsar_jaas.conf
file path as a JVM parameter. For example:
-Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf
:::note
If your machines configured with Kerberos already have a system-wide configuration, you can skip this configuration.
:::
The content of krb5.conf
file indicates the default Realm and KDC information. See JDK's Kerberos Requirements for more details.
To specify the path to the krb5.conf
file for brokers, enter the command below.
-Djava.security.krb5.conf=/etc/pulsar/krb5.conf
Here is an example of the krb5.conf
file.
[libdefaults] default_realm = EXAMPLE.COM [realms] EXAMPLE.COM = { kdc = localhost:62037 }
In the above example:
EXAMPLE.COM
is the default Realm;kdc = localhost:62037
is the KDC server URL for the EXAMPLE.COM
Realm.If you want to use proxies between brokers and clients, Pulsar proxies (as a SASL server in Kerberos) will authenticate clients (as a SASL client in Kerberos) before brokers authenticate proxies.
To enable Kerberos authentication on proxies, complete the following steps.
Add new principals for Pulsar proxies.
### add Principals for Pulsar Proxy 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}"
For principals set for brokers and clients, see here.
In the proxy.conf
file, set Kerberos-related configuration.
## related to authenticate client. authenticationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl saslJaasClientAllowedIds=.*client.* saslJaasServerSectionName=PulsarProxy ## related to be authenticated by broker brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarProxy", "serverType":"broker"} forwardAuthorizationCredentials=true
In the above example:
Add a new section for proxies in the pulsar_jaas.conf
file. Here is an example:
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"; };
:::note
Ensure that the operating system user who starts Pulsar clients can access the keytabs configured in the pulsar_jaas.conf
file and the KDC server configured in the krb5.conf
file.
:::
In client applications, include pulsar-client-auth-sasl
in your project dependency.
<dependency> <groupId>org.apache.pulsar</groupId> <artifactId>pulsar-client-auth-sasl</artifactId> <version>${pulsar.version}</version> </dependency>
Configure the authentication type to use AuthenticationSasl
and provide the following parameters.
saslJaasClientSectionName
to PulsarClient
;serverType
to broker
. serverType
stands for whether this client connects to brokers or proxies. Clients use this parameter to know which server-side principal should be used.The following is an example of configuring 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();
:::note
serverType
to proxy
instead of broker
.pulsar_jaas.conf
and krb5.conf
files 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
:::
Command-line tools like pulsar-admin
, pulsar-perf
, and pulsar-client
use the conf/client.conf
file in a Pulsar installation.
When using command-line tools, you need to perform the following steps:
Configure the conf/client.conf
file.
authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl authParams={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
Set JVM parameters for the pulsar_jaas.conf
file and krb5.conf
files with additional options.
-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
, 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 the meaning of configurations in Java client section.
Pulsar broker acts as a Kerberos client when authenticating with Zookeeper.
Add the settings in conf/zookeeper.conf
.
authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider requireClientAuthScheme=sasl
Enter the following commands to add a section of Client
configurations in pulsar_jaas.conf
that Pulsar broker uses:
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"; };
In this setting, the principal of Pulsar broker and keytab file indicates the role of brokers when you authenticate with ZooKeeper.
For more information, see ZooKeeper document
Pulsar broker acts as a Kerberos client when authenticating with Bookie.
Add the bookkeeperClientAuthenticationPlugin
parameter in broker.conf
.
bookkeeperClientAuthenticationPlugin=org.apache.bookkeeper.sasl.SASLClientProviderFactory
SASLClientProviderFactory
creates a BookKeeper SASL client in a broker, and the broker uses the created SASL client to authenticate with a Bookie node.
Add a section of BookKeeper
configurations in the pulsar_jaas.conf
file that broker/proxy uses.
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"; };
In this setting, the principal of Pulsar broker and keytab file indicates the role of brokers when you authenticate with Bookie.
For more information, see BookKeeper document.