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
| Role | Bound to | For |
|---|---|---|
| DeveloperRead | a pattern | an application that consumes: it reads the topics and joins the consumer groups under its pattern |
| DeveloperWrite | a pattern | an application that produces: it writes the topics under its pattern, transactionally if it wants |
| DeveloperManage | a pattern | a team that creates and deletes its own topics and groups, and runs its own connectors, without reading or writing the data |
| ResourceOwner | a pattern | the owner of a pattern: everything on what it covers, and the right to hand out roles inside it |
| ResourceViewer | a pattern | someone who needs to see what exists under a pattern and how it is configured, without reading the data |
| ClusterAdmin | the cluster | an operator who runs the cluster, without reading or writing the data in topics; it does not manage access |
| SystemAdmin | the cluster | everything, 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.
- Nothing else to run. The record lives in the cluster's metadata next to the ACLs and reaches every node the way an ACL does: no service, no directory server, no topic to create.
- The tools you have keep working. The ACL tool, the admin client and whatever manages your ACLs today create, list and delete bindings.
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:
- The ACLs first, exactly as
StandardAuthorizeranswers them. What they allow is allowed, and no role is asked. - If the ACLs did not allow it and a deny ACL matches it, it is denied.
- Otherwise it is allowed when a role bound to the principal, or to a group
it is in, covers it, or an
ALLOWACL 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.
- Nothing is granted on failure. An exception, a binding that cannot be
read, a role that is unknown: none of them is ever
ALLOWED. - No request is decided from half of the bindings. Until a node has loaded
the ACL records, its authorizer answers the principals in
super.usersand nobody else. - The ACLs you have keep working, and nothing changes until the first role is bound.
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.
- A role is bound to a group instead of to every user in it:
DeveloperRead:Group:payments. - An ordinary
ALLOWACL whose principal is a group works for its members. This is how a set of permissions that no role names is given to many users at once. - A group only adds access. A
DENYACL that names a group cannot be created: deny the users by name. - There is no directory to connect and nothing else to run. A group is not a member of a group.
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:
| Who | May 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 denies | any binding, any group membership and any ACL, as before there were roles |
| a principal that holds SystemAdmin | any binding, any group membership and any ACL |
| a principal that holds ResourceOwner | bindings 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 included | nothing |
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
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
- A connector is the resource
Connector:<name>: a binding on the prefixConnector:billing-covers the connectors whose names start withbilling-. - The caller is whoever the worker authenticated: the user of HTTP basic authentication, or the subject of the client certificate. An anonymous request is refused.
- The worker reads the bindings again every five seconds. A refusal is a 403 that says which operation on which connector was missing.
- For connectors only roles grant: an ordinary ACL means nothing to the extension.
12 · what is not there
What it does not do
- Nothing for schemas yet. The roles say what they would grant on the subjects of a schema registry, and a binding for subjects can be written, but nothing reads it.
- No roles of your own. There are the seven. A set of permissions that none of them names is given with ordinary ACLs to a group.
- No groups from a directory. A principal is in the groups that membership records put it in, and in no other.
- No dashboard of its own. The access metrics are those of kfkwho, under its names, and off by default.
- No way to become a super user. No role but
SystemAdminlets its holder replace a user's SCRAM credentials. - No narrowed listing. To manage its bindings an owner has to list them,
and the listing of ACLs cannot be narrowed to the caller: a
ResourceOwnersees every binding and every ACL of the cluster.
13 · why believe any of this
How it is tested
- Unit tests drive the real
StandardAuthorizer, the command and the extension's filter, without a broker. A test that shows a role allowing a request has a twin that shows the same request denied without it. - Integration tests run the built jar as the authorizer of real brokers and the extension of real Connect workers, in containers, on Kafka 4.1 to 4.4.
- The documents are held to the code. Every shell command in the documents is run against a real broker by a test, and its output compared with what the page shows, or the page says next to it that it was not.
- Benchmarks measure the cost of
authorize(), which runs for every topic of every Fetch and Produce.
Nothing has run on a production cluster yet.
14 · go
One jar, one line
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.
- Source on GitHub
- Installation, Roles, Bindings, Delegation, Groups
- The command, Bringing bindings over, Kafka Connect, Troubleshooting
- Releases, Maven Central
- kfkit
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