Authentication and authorization in Pulsar


In Pulsar, the authentication provider is charged with properly identifying clients and associating them with role tokens. Authorization is the process that determines what clients are able to do.

Authorization in Pulsar is managed at the tenant level, which means that you can have multiple authorization schemes active in a single Pulsar instance. You could, for example, create a shopping tenant that has one set of roles and applies to a shopping application used by your company, while an inventory tenant would be used only by an inventory application.

When working with properties, you can specify which of your Pulsar clusters your property is allowed to use. This enables you to also have cluster-level authorization schemes.

Creating a new tenant

A Pulsar tenant is typically provisioned by Pulsar instance administrators or by some kind of self-service portal.

Tenants are managed using the pulsar-admin tool. Here’s an example tenant creation command:

$ bin/pulsar-admin tenants create my-tenant \
  --admin-roles my-admin-role \
  --allowed-clusters us-west,us-east

This command will create a new tenant my-tenant that will be allowed to use the clusters us-west and us-east.

A client that successfully identified itself as having the role my-admin-role would then be allowed to perform all administrative tasks on this property.

The structure of topic names in Pulsar reflects the hierarchy between tenants, clusters, and namespaces:

persistent://tenant/namespace/topic

Managing permissions

Permissions in Pulsar are managed at the namespace level (that is, within properties and clusters).

Grant permissions

You can grant permissions to specific roles for lists of operations such as produce and consume.

pulsar-admin

Use the grant-permission subcommand and specify a namespace, actions using the --actions flag, and a role using the --role flag:

$ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
  --actions produce,consume \
  --role admin10

Wildcard authorization can be performed when authorizationAllowWildcardsMatching is set to true in broker.conf.

e.g.

$ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
                        --actions produce,consume \
                        --role 'my.role.*'

Then, roles my.role.1, my.role.2, my.role.foo, my.role.bar, etc. can produce and consume.

$ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
                        --actions produce,consume \
                        --role '*.role.my'

Then, roles 1.role.my, 2.role.my, foo.role.my, bar.role.my, etc. can produce and consume.

Note: A wildcard matching works at the beginning or end of the role name only.

e.g.

$ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
                        --actions produce,consume \
                        --role 'my.*.role'

In this case, only the role my.*.role has permissions.
Roles my.1.role, my.2.role, my.foo.role, my.bar.role, etc. cannot produce and consume.

REST API

POST/admin/namespaces/:property/:cluster/:namespace/permissions/:role

More info

Java

admin.namespaces().grantPermissionOnNamespace(namespace, role, getAuthActions(actions));

Get permission

You can see which permissions have been granted to which roles in a namespace.

pulsar-admin

Use the permissions subcommand and specify a namespace:

$ pulsar-admin namespaces permissions test-property/cl1/ns1
{
  "admin10": [
    "produce",
    "consume"
  ]
}   

REST API

GET/admin/namespaces/:property/:cluster/:namespace/permissions

More info

Java

admin.namespaces().getPermissions(namespace);

Revoke permissions

You can revoke permissions from specific roles, which means that those roles will no longer have access to the specified namespace.

pulsar-admin

Use the revoke-permission subcommand and specify a namespace and a role using the --role flag:

$ pulsar-admin namespaces revoke-permission test-property/cl1/ns1 \
  --role admin10

REST API

DELETE/admin/namespaces/:property/:cluster/:namespace/permissions/:role

More info

Java

admin.namespaces().revokePermissionsOnNamespace(namespace, role);

Superusers

In Pulsar you can assign certain roles to be superusers of the system. A superuser is allowed to perform all administrative tasks on all tenants and namespaces, as well as to publish and subscribe to all topics.

Superusers are configured in the broker configuration file in conf/broker.conf configuration file, using the superUserRoles parameter:

superUserRoles=my-super-user-1,my-super-user-2

A full listing of parameters available in the conf/broker.conf file, as well as the default values for those parameters, can be found in Broker Configuration.

Typically, superuser roles are used for administrators and clients but also for broker-to-broker authorization. When using geo-replication, every broker needs to be able to publish to other clusters’ topics.

Pulsar admin authentication

String authPluginClassName = "com.org.MyAuthPluginClass";
String authParams = "param1:value1";
boolean useTls = false;
boolean tlsAllowInsecureConnection = false;
String tlsTrustCertsFilePath = null;

ClientConfiguration config = new ClientConfiguration();
config.setAuthentication(authPluginClassName, authParams);
config.setUseTls(useTls);
config.setTlsAllowInsecureConnection(tlsAllowInsecureConnection);
config.setTlsTrustCertsFilePath(tlsTrustCertsFilePath);

PulsarAdmin admin = new PulsarAdmin(url, config);

To use TLS:

String authPluginClassName = "com.org.MyAuthPluginClass";
String authParams = "param1:value1";
boolean useTls = false;
boolean tlsAllowInsecureConnection = false;
String tlsTrustCertsFilePath = null;

ClientConfiguration config = new ClientConfiguration();
config.setAuthentication(authPluginClassName, authParams);
config.setUseTls(useTls);
config.setTlsAllowInsecureConnection(tlsAllowInsecureConnection);
config.setTlsTrustCertsFilePath(tlsTrustCertsFilePath);

PulsarAdmin admin = new PulsarAdmin(url, config);