Skip to main content
Version: 2.11.x

Authentication using OAuth 2.0 access tokens

Pulsar supports authenticating clients using OAuth 2.0 access tokens. Using an access token obtained from an OAuth 2.0 authorization service (acts as a token issuer), you can identify a Pulsar client and associate it with a "principal" (or "role") that is permitted to do some actions, such as publishing messages to a topic or consuming messages from a topic.

After communicating with the OAuth 2.0 server, the Pulsar client gets an access token from the server and passes this access token to brokers for authentication. By default, brokers can use the org.apache.pulsar.broker.authentication.AuthenticationProviderToken. Alternatively, you can customize the value of AuthenticationProvider.

Enable OAuth2 authentication on brokers/proxies

To configure brokers/proxies to authenticate clients using OAuth2, add the following parameters to the conf/broker.conf and the conf/proxy.conf file. If you use a standalone Pulsar, you need to add these parameters to the conf/standalone.conf file:

# Configuration to enable authentication
authenticationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken

# 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.oauth2.AuthenticationOAuth2
brokerClientAuthenticationParameters={"privateKey":"file:///path/to/privateKey","audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/","issuerUrl":"https://dev-kt-aa9ne.us.auth0.com"}
# brokerClientAuthenticationParameters={"privateKey":"data:application/json;base64,privateKey-body-to-base64","audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/","issuerUrl":"https://dev-kt-aa9ne.us.auth0.com"}

# If using secret key (Note: key files must be DER-encoded)
tokenSecretKey=file:///path/to/secret.key
# The key can also be passed inline:
# tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU=

# If using public/private (Note: key files must be DER-encoded)
# tokenPublicKey=file:///path/to/public.key

Configure OAuth2 authentication in Pulsar clients

You can use the OAuth2 authentication provider with the following Pulsar clients.

import org.apache.pulsar.client.impl.auth.oauth2.AuthenticationFactoryOAuth2;

URL issuerUrl = new URL("https://dev-kt-aa9ne.us.auth0.com");
URL credentialsUrl = new URL("file:///path/to/KeyFile.json");
String audience = "https://dev-kt-aa9ne.us.auth0.com/api/v2/";

PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar://broker.example.com:6650/")
.authentication(
AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credentialsUrl, audience))
.build();

In addition, you can also use the encoded parameters to configure authentication for Pulsar Java client.

Authentication auth = AuthenticationFactory
.create(AuthenticationOAuth2.class.getName(), "{"type":"client_credentials","privateKey":"./key/path/..","issuerUrl":"...","audience":"..."}");
PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar://broker.example.com:6650/")
.authentication(auth)
.build();

Configure OAuth2 authentication in CLI tools

This section describes how to use Pulsar CLI tools to connect a cluster through OAuth2 authentication plugin.

bin/pulsar-admin --admin-url https://streamnative.cloud:443 \
--auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
--auth-params '{"privateKey":"file:///path/to/key/file.json",
"issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
tenants list
  • Set the admin-url parameter to the Web service URL. A Web service URL is a combination of the protocol, hostname and port ID, such as pulsar://localhost:6650.
  • Set the privateKey, issuerUrl, and audience parameters to the values based on the configuration in the key file. For details, see authentication types.

Authentication types

Currently, Pulsar clients only support the client_credentials authentication type. The authentication type determines how to obtain an access token through an OAuth 2.0 authorization service.

The following table outlines the parameters of the client_credentials authentication type.

ParameterDescriptionExampleRequired or not
typeOAuth 2.0 authentication type.client_credentials (default)Optional
issuerUrlThe URL of the authentication provider which allows the Pulsar client to obtain an access token.https://accounts.google.comRequired
privateKeyThe URL to the JSON credentials file.Support the following pattern formats:
  • file:///path/to/file
  • file:/path/to/file
  • data:application/json;base64,<base64-encoded value>
  • Required
    audienceThe OAuth 2.0 "resource server" identifier for a Pulsar cluster.https://broker.example.comOptional
    scopeThe scope of an access request.
    For more information, see access token scope.
    api://pulsar-cluster-1/.defaultOptional

    The credentials file credentials_file.json contains the service account credentials used with the client authentication type. The following is an example of the credentials file. The authentication type is set to client_credentials by default. And the fields "client_id" and "client_secret" are required.

    {
    "type": "client_credentials",
    "client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",
    "client_secret": "on1uJ...k6F6R",
    "client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",
    "issuer_url": "https://accounts.google.com"
    }

    The following is an example of a typical original OAuth2 request, which is used to obtain an access token from the OAuth2 server.

    curl --request POST \
    --url https://dev-kt-aa9ne.us.auth0.com/oauth/token \
    --header 'content-type: application/json' \
    --data '{
    "client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
    "client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
    "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
    "grant_type":"client_credentials"}'

    In the above example, the mapping relationship is shown below.

    • The issuerUrl parameter is mapped to --url https://dev-kt-aa9ne.us.auth0.com.
    • The privateKey parameter should contain the client_id and client_secret fields at least.
    • The audience parameter is mapped to "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/". This field is only used by some identity providers.