The ACL (Access Control List) policy manages authorization for your virtual cluster by defining which actions principals can perform on specific resources.
By default, when ACLs are enabled, principals have no access. You must explicitly define access rules through ACL policies.
Common use cases for the ACLs policy:
|
Use case |
Description |
|---|---|
| Example: Allow read-only access to a topic | Allow the principal to consume messages for a specific topic. |
| Example: Allow consumer group management | Allow the principal to create and delete consumer groups. |
| How-to: Productize Kafka topics with namespaces and ACLs | If your Kafka topics follow a naming convention with prefixes, you can easily organize them into categories with Kong Event Gateway by using a combination of namespaces, forwarding policies, and ACL policies. |
| How-to: Secure Kafka traffic in Event Gateway with Kong Identity and ACLs | Using Kong Identity as an auth server, verify client OAuth tokens through a virtual cluster, and apply an ACL policy to restrict access to a specific client. |
This policy runs in the cluster phase.
sequenceDiagram autonumber participant client as Client participant egw as Event Gateway participant broker as Event broker client->>egw: message egw->>egw: check action against ACL alt If action allowed egw->>broker: send message else If action blocked egw -x client: forbidden end
When the virtual cluster uses terminate mediation, the Event Gateway connects to the backend Kafka cluster using a single service account.
The backend cluster sees only that service account, not individual client identities.
ACL policies on the virtual cluster are how you enforce per-client authorization in this model.
Each client’s principal is evaluated against ACL rules before the Event Gateway forwards any request to the backend.
Consumer Group management commands (for example, create or delete) are also intercepted and evaluated against ACL rules using the group resource type.
The ACL policy decides whether a principal can perform an action at all, based on the resource, operation, and permission type. It doesn’t inspect the content of the request beyond the resource name.
If you need to constrain the content of an allowed action, for example capping the number of partitions a client can request or enforcing a topic naming pattern, use the Request Rule Validator policy instead.
You can combine both policies on the same virtual cluster: ACLs decide who can act, and Request Rule Validator decides what the action contains. We recommend placing ACLs before Request Rule Validator, so an unauthorized client learns nothing about your content rules before it’s rejected on authorization grounds.
When resource_names uses an expression that interpolates an identity into a glob pattern (for example {{[context.auth.principal.name + "-*"]}} or {{[context.auth.token.claims.topic_prefix + "*"]}}), the interpolated value is matched as a glob and is not escaped. If the value can contain glob metacharacters (*, ?, [, ]), they act as wildcards and can widen the set of matched resources beyond what you intend.
For example, with resource_names: '{{[context.auth.principal.name + "-*"]}}', a principal named ali* produces the pattern ali*-*, which matches topics such as alibob-secrets and ali-data, not just that principal’s own topics.
Only interpolate identity values into resource_names patterns when those values are guaranteed not to contain glob metacharacters.
The ACL policy logs each decision type at a different level:
trace level.debug level.By default, Event Gateway logs at the info level, which excludes these logs.
Kafka usually has high traffic, and logging every decision could overwhelm the logging system.
To show ACL decisions without raising the level for the whole gateway, set the debug level for the ACL module only:
KEG__OBSERVABILITY__LOG_FLAGS=info,keg::kafka::proxy::transform::policies::acl=debug