kfkrbac, roles for Apache Kafka®

Roles.
On top of
the ACLs.

One jar, one line of configuration, nothing else to run. This is how it works, in fifteen slides and one small model.

Scroll, or use the arrow keys.

1 · the problem

ACLs multiply

An ACL binds one principal to one resource. With tens of teams and hundreds of topics the ACLs multiply, nobody can say what a team is allowed to do, and bringing one more service on is a list of commands to run.

2 · the idea

Name the permissions once

A role names a set of permissions once. A role binding hands it to a user or a group, for a topic, a prefix or the whole cluster.

One binding for one application: a role bound to the prefix billing. covers the topics, the consumer groups and the transactional IDs that start with it.

The measure of every choice here: roles without a separate service to deploy, a directory server to depend on, several bindings for one application, or denials that do not say what was missing.

3 · the roles

Seven roles

RoleBound toFor
DeveloperReada patternan application that consumes: it reads the topics and joins the consumer groups under its pattern
DeveloperWritea patternan application that produces: it writes the topics under its pattern, transactionally if it wants
DeveloperManagea patterna team that creates and deletes its own topics and groups, and runs its own connectors, without reading or writing the data
ResourceOwnera patternthe owner of a pattern: everything on what it covers, and the right to hand out roles inside it
ResourceViewera patternsomeone who needs to see what exists under a pattern and how it is configured, without reading the data
ClusterAdminthe clusteran operator who runs the cluster, without reading or writing the data in topics; it does not manage access
SystemAdminthe clustereverything, everywhere, including binding any role to anyone

What each grants, operation by operation, is in Roles, and a test fails when that table and the code disagree. A role's meaning never changes once it is released.

4 · the record

A binding is an ACL record

Its principal names the role and the member: DeveloperRead:User:alice, on the prefixed pattern billing., with the operation All. No client is ever a principal of type DeveloperRead, so the broker's own authorizer never matches the record. RbacAuthorizer reads it as the member holds the role on that pattern.

kafka-acls.sh --bootstrap-server localhost:9092 --command-config admin.properties \
  --add --allow-principal DeveloperRead:User:alice --operation All \
  --topic billing. --resource-pattern-type prefixed

Mind a tool that keeps the ACLs equal to a list in a file: to it a binding that is not in its list is an ACL to delete.

5 · the decision

How a request is decided

RbacAuthorizer is the broker's StandardAuthorizer with roles added. The broker asks it about every resource of every request:

  1. The ACLs first, exactly as StandardAuthorizer answers them. What they allow is allowed, and no role is asked.
  2. If the ACLs did not allow it and a deny ACL matches it, it is denied.
  3. Otherwise it is allowed when a role bound to the principal, or to a group it is in, covers it, or an ALLOW ACL of such a group allows it; and denied when none does or the roles cannot be read.

The broker's second question, may this principal do this on any resource of the type, is answered the same way.

6 · what it guarantees

Roles only add

A role only adds access. What a deny ACL denies stays denied, whatever roles the principal holds, so denying is done with ACLs.

One setting to mind: with allow.everyone.if.no.acl.found=true the first binding on a pattern takes away what everyone had on it by default. Leave it at its default, false, to use roles.

7 · groups

Groups, in the same metadata

A group is a name and the principals that membership records put in it. A membership is an ACL record too: the principal Member:User:alice, on the literal topic name Group:payments. No topic can be called that: a colon is not legal in a topic name.

8 · delegation

The owner of a prefix hands out roles inside it

And nowhere else. Bindings are created and deleted through the ACL API, and the cluster decides each request by who sent it:

WhoMay create and delete
a principal that the ACLs allow to alter the cluster: one in super.users, or one that an ACL allows Alter on the cluster and none deniesany binding, any group membership and any ACL, as before there were roles
a principal that holds SystemAdminany binding, any group membership and any ACL
a principal that holds ResourceOwnerbindings of the five roles that are bound to a pattern, to users and to groups, on patterns inside what it owns
everyone else, a ClusterAdmin includednothing

The decision is made on the controller, when the record is created or deleted: one reason the jar is on the controllers too. A request is decided as a whole, and the caller gets the reason back.

9 · try it

Bind a role

as
request
binding
admin
asks as User:alice verdict nothing asked yet asked nothing yet why – bindings none in Group:payments nobody ACLs none

    A model of the rules above, not the real code: three users, of whom User:admin is in super.users, one group, the five roles that are bound to a pattern, and one question for each thing a request needs. A real client asks more: a producer is first asked whether it may write any topic at all. Consume as User:alice: denied. Bind DeveloperRead to her as User:admin and ask again. Then make User:bob the ResourceOwner of the prefix and bind as him, inside it and outside.

    10 · when it says no

    A denial says what was missing

    The client's error names a topic or a group and nothing more. The broker's log has the rest, one line for the denied request:

    Denied User:alice DESCRIBE on GROUP 'billing-1' (request FindCoordinator): no ACL and no role allows it; roles held for GROUP: DeveloperRead on prefix billing.

    Who asked, for what, why not, and which roles the principal does hold: the binding is on billing. and the group is billing-1.

    The command of the jar answers before a client fails: who-can names who may do an operation on a resource, and why; what-can lists what a principal may do. It also binds and lists, keeps bindings in a file (apply) and brings them over from files of two other shapes (import). It is a convenience, never the only way: everything it does can be done with the ACL tool as well.

    11 · outside the broker

    Connectors, from the same bindings

    A broker never sees the requests to the REST interface of Kafka Connect. So the workers take the same jar as an extension of their own, with one line in their settings:

    rest.extension.classes=dev.kfkit.kfkrbac.connect.RbacConnectRestExtension

    12 · what is not there

    What it does not do

    13 · why believe any of this

    How it is tested

    Nothing has run on a production cluster yet.

    14 · go

    One jar, one line

    Source on GitHub ▶ Releases ▶

    On every node, controllers included: copy the jar to libs/, and name the class where the node's configuration names its authorizer.

    cp kfkrbac-*.jar "$KAFKA_HOME/libs/"
    sed -i 's/^authorizer\.class\.name=.*/authorizer.class.name=dev.kfkit.kfkrbac.RbacAuthorizer/' \
      "$KAFKA_HOME/config/server.properties"

    Then restart, node by node. That is for a cluster that has an authorizer already. A cluster that has none starts enforcing ACLs the moment it has the line: read Installation first. A principal that is in super.users, here User:admin, binds the first role:

    kafka-run-class.sh dev.kfkit.kfkrbac.RbacCommand bind \
      --bootstrap-server localhost:9092 --command-config admin.properties \
      --role DeveloperRead --member User:alice --prefix billing.

    Kafka 4.1 and later, in KRaft mode. The jar, its SHA-256 and its signature are on the releases page, and the same jar is on Maven Central as dev.kfkit:kfkrbac.

    With Claude Code, the repository carries a skill for adopting kfkrbac: what to find out first, the order of the steps, what not to do.

    /plugin marketplace add kfkit/kfkrbac
    /plugin install kfkrbac@kfkrbac