Client authentication using OAuth 2.0 access tokens

This module is used to support the Pulsar client authentication plugin for OAuth 2.0. After communicating with the OAuth 2.0 server, the Pulsar client gets an from the OAuth 2.0 server, and passes this access token to the Pulsar broker to do the authentication. The broker can use the org.apache.pulsar.broker.authentication.AuthenticationProviderToken. Or, you can add your own AuthenticationProvider to make it with this module.

This library allows you to authenticate the Pulsar client by using an access token that is obtained from an OAuth 2.0 authorization service, which acts as a token issuer.

The authentication type determines how to obtain an access token through an OAuth 2.0 authorization flow.

note

Currently, the Pulsar Java client only supports the client_credentials authentication type .

Client credentials

The following table lists parameters supported for the client credentials authentication type.

The credentials file contains service account credentials used with the client authentication type. The following shows an example of a credentials file credentials_file.json.

In the above example, the authentication type is set to client_credentials by default. And the fields “client_id” and “client_secret” are required.

Typical original OAuth2 request mapping

  1. curl --request POST \
  2. --url https://dev-kt-aa9ne.us.auth0.com \
  3. --header 'content-type: application/json' \
  4. --data '{
  5. "client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
  6. "client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
  7. "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
  8. "grant_type":"client_credentials"}'

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

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

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

Java client

You can use the factory method to configure authentication for Pulsar Java client.

  1. URL issuerUrl = new URL("https://dev-kt-aa9ne.us.auth0.com");
  2. URL credentialsUrl = new URL("file:///path/to/KeyFile.json");
  3. String audience = "https://dev-kt-aa9ne.us.auth0.com/api/v2/";
  4. PulsarClient client = PulsarClient.builder()
  5. .authentication(
  6. AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credentialsUrl, audience))
  7. .build();

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

The C++ client is similar to the Java client. You need to provide the parameters of , private_key (the credentials file path), and audience.

  1. #include <pulsar/Client.h>
  2. pulsar::ClientConfiguration config;
  3. std::string params = R"({
  4. "issuer_url": "https://dev-kt-aa9ne.us.auth0.com",
  5. "private_key": "../../pulsar-broker/src/test/resources/authentication/token/cpp_credentials_file.json",
  6. "audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/"})";
  7. config.setAuth(pulsar::AuthOauth2::create(params));
  8. pulsar::Client client("pulsar://broker.example.com:6650/", config);

Go client

To enable OAuth2 authentication in Go client, you need to configure OAuth2 authentication. This example shows how to configure OAuth2 authentication in Go client.

  1. oauth := pulsar.NewAuthenticationOAuth2(map[string]string{
  2. "type": "client_credentials",
  3. "issuerUrl": "https://dev-kt-aa9ne.us.auth0.com",
  4. "audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/",
  5. "privateKey": "/path/to/privateKey",
  6. "clientId": "0Xx...Yyxeny",
  7. })
  8. client, err := pulsar.NewClient(pulsar.ClientOptions{
  9. URL: "pulsar://my-cluster:6650",
  10. Authentication: oauth,
  11. })

Python client

To enable OAuth2 authentication in Python client, you need to configure OAuth2 authentication. This example shows how to configure OAuth2 authentication in Python client.

  1. const Pulsar = require('pulsar-client');
  2. const issuer_url = process.env.ISSUER_URL;
  3. const private_key = process.env.PRIVATE_KEY;
  4. const audience = process.env.AUDIENCE;
  5. const scope = process.env.SCOPE;
  6. const service_url = process.env.SERVICE_URL;
  7. const client_id = process.env.CLIENT_ID;
  8. const client_secret = process.env.CLIENT_SECRET;
  9. const params = {
  10. issuer_url: issuer_url
  11. }
  12. if (private_key.length > 0) {
  13. params['private_key'] = private_key
  14. } else {
  15. params['client_id'] = client_id
  16. params['client_secret'] = client_secret
  17. if (audience.length > 0) {
  18. params['audience'] = audience
  19. }
  20. if (scope.length > 0) {
  21. params['scope'] = scope
  22. }
  23. const auth = new Pulsar.AuthenticationOauth2(params);
  24. // Create a client
  25. const client = new Pulsar.Client({
  26. serviceUrl: service_url,
  27. tlsAllowInsecureConnection: true,
  28. authentication: auth,
  29. });
  30. await client.close();
  31. })();

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

pulsar-admin

This example shows how to use pulsar-admin to connect to a cluster through OAuth2 authentication plugin.

  1. bin/pulsar-admin --admin-url https://streamnative.cloud:443 \
  2. --auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
  3. --auth-params '{"privateKey":"file:///path/to/key/file.json",
  4. "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
  5. "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
  6. tenants list

Set the admin-url parameter to the Web service URL. A Web service URLis 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.

pulsar-client

This example shows how to use pulsar-client to connect to a cluster through OAuth2 authentication plugin.

Set the admin-url parameter to the Web service URL. A Web service URLis 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.

This example shows how to use pulsar-perf to connect to a cluster through OAuth2 authentication plugin.

  1. bin/pulsar-perf produce --service-url pulsar+ssl://streamnative.cloud:6651 \
  2. --auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
  3. --auth-params '{"privateKey":"file:///path/to/key/file.json",
  4. "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
  5. -r 1000 -s 1024 test-topic