Pulsar Client

Table of Contents

1. TLS Encryption (SSL)
2. Authentication

When you use the Pulsar Spring Boot Starter, you get the PulsarClient auto-configured.

By default, the application tries to connect to a local Pulsar instance at pulsar://localhost:6650. This can be adjusted by setting the spring.pulsar.client.service-url property to a different value.

The value must be a valid Pulsar Protocol URL

You can further configure the client by specifying any of the spring.pulsar.client.* application properties.

If you are not using the starter, you will need to configure and register the PulsarClient yourself. There is a DefaultPulsarClientFactory that accepts a builder customizer that can be used to help with this.

1. TLS Encryption (SSL)

By default, Pulsar clients communicate with Pulsar services in plain text. The following section describes how to configure Pulsar clients to use TLS encryption (SSL). A pre-requisite is that the Broker has also been configured to use TLS encryption.

The Spring Boot auto-configuration does not currently support any TLS/SSL configuration properties. You can instead provide a PulsarClientBuilderCustomizer that sets the necessary properties on the Pulsar client builder. Pulsar supports both Privacy Enhanced Mail (PEM) and Java KeyStore (JKS) certificate formats.

Follow these steps to configure TLS:

Adjust the Pulsar client service url to use the pulsar+ssl:// scheme and TLS port (typically 6651).
Adjust the admin client service url to use the https:// scheme and TLS web port (typically 8443).
Provide client builder customizer(s) that sets the relevant properties on the builder.
- PEM based sample
- JKS based sample

You can find more information on the above in the official Pulsar TLS Encryption documentation.

2. Authentication

To connect to a Pulsar cluster that requires authentication, you need to specify which authentication plugin to use and any parameters required by the specified plugin. When using Spring Boot auto-configuration, you can set the plugin and the plugin parameters via configuration properties (in most cases).

You need to ensure that names defined under spring.pulsar.client.authentication.param.* exactly match those expected by your auth plugin (which is typically camel cased). Spring Boot will not attempt any kind of relaxed binding for these entries.

For example, if you want to configure the issuer url for the AuthenticationOAuth2 auth plugin you must use spring.pulsar.client.authentication.param.issuerUrl. If you use other forms, such as issuerurl or issuer-url, the setting will not be applied to the plugin.

Using environment variables for auth parameters is typically problematic because the case sensitivity is lost during translation. For example, consider the following issuerUrl auth parameter set via an environment variable:

SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com

When Spring Boot loads this property it will use issuerurl (lower-cased) rather than the expected issuerUrl (camel-cased). You can get around this limitation by using the value of the env var as the value of the related auth property in your application.yml. Continuing the example above:

spring:
  pulsar:
    client:
      authentication:
        param:
          issuerUrl: ${SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL}

When not using Spring Boot auto-configuration, you can use the org.apache.pulsar.client.api.AuthenticationFactory to create the authentication and then set it directly on the Pulsar client builder in a client customizer that you provide to the client factory.

The following listings show how to configure each of the supported authentication mechanisms.

Click here for Athenz

spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationAthenz
        param:
          tenantDomain: ...
          tenantService: ...
          providerDomain: ...
          privateKey: ...
          keyId: ...

This also requires TLS encryption.

Click here for Token

spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken
        param:
          token: some-token-goes-here

Click here for Basic

spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationBasic
        param:
          userId: ...
          password: ...

Click here for OAuth2

spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2
        param:
          issuerUrl: ...
          privateKey: ...
          audience: ...
          scope: ...

Click here for Sasl

spring:
  pulsar:
    client:
      authentication:
        plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationSasl
        param:
          saslJaasClientSectionName: ...
          serverType: ...

Click here for mTLS (PEM)

Because this option requires TLS encryption, which already requires you to provide a client builder customizer, it is recommended to simply add the authentication directly on the client builder in your provided TLS customizer. You can use the org.apache.pulsar.client.api.AuthenticationFactory to help create the authentication object as follows:

Authentication auth = AuthenticationFactory.TLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem");

See the official Pulsar documentation on mTLS (PEM).

Click here for mTLS (JKS)

Authentication auth = AuthenticationFactory.create(
        "org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls",
        Map.of("keyStoreType", "JKS", "keyStorePath", "/path/to/my/keystore.jks", "keyStorePassword", "clientpw"));

See the official Pulsar documentation on mTLS (JKS).

You can find more information on each of the support plugins and their required properties in the official Pulsar security documentation.