diff --git a/app/_event_gateway_policies/acl/index.md b/app/_event_gateway_policies/acl/index.md
index 113c6206cf2..27f52e89b91 100644
--- a/app/_event_gateway_policies/acl/index.md
+++ b/app/_event_gateway_policies/acl/index.md
@@ -100,6 +100,13 @@ sequenceDiagram
{% endmermaid %}
+When the virtual cluster uses [`terminate` mediation](/event-gateway/entities/virtual-cluster/#credential-mediation), the {{site.event_gateway_short}} 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](/event-gateway/entities/virtual-cluster/) are how you enforce per-client authorization in this model.
+
+Each client's principal is evaluated against ACL rules before the {{site.event_gateway_short}} 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.
+
## Security considerations
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.
diff --git a/app/event-gateway/entities/backend-cluster.md b/app/event-gateway/entities/backend-cluster.md
index b5165792f60..02b0d6788ae 100644
--- a/app/event-gateway/entities/backend-cluster.md
+++ b/app/event-gateway/entities/backend-cluster.md
@@ -23,13 +23,6 @@ tags:
works_on:
- konnect
-# schema:
-# api: event-gateway/
-# path: /schemas/
-
-# api_specs:
-# - konnect/event-gateway
-
products:
- event-gateway
api_specs:
@@ -59,10 +52,8 @@ Multiple Kafka clusters can be proxied through a single {{site.event_gateway}}.
## Authentication
-Authentication on the backend cluster defines how the proxy connects to the backend for capturing metadata (topics, consumer groups, and so on).
-
-The backend cluster supports multiple authentication methods and can mediate authentication between clients and backend clusters.
-See [Virtual cluster authentication](/event-gateway/entities/virtual-cluster/#authentication) to learn more.
+Authentication on the backend cluster defines the credentials the {{site.event_gateway_short}} uses when connecting to Kafka on behalf of clients.
+The supported types reflect what your Kafka cluster accepts.
Backend clusters support the following auth methods:
@@ -97,6 +88,11 @@ rows:
`passthrough`
{% endtable %}
+Depending on what your Kafka cluster supports, you'll need to configure authentication on the associated virtual cluster:
+* If your Kafka cluster only accepts SASL/PLAIN or SASL/SCRAM credentials, configure [`terminate` mediation on the virtual cluster](/event-gateway/entities/virtual-cluster/#credential-mediation) so the {{site.event_gateway_short}} translates client credentials into the backend's accepted mechanism.
+* If your backend Kafka cluster supports SASL/OAUTHBEARER natively, use [`passthrough` or `validate_forward` mediation](/event-gateway/entities/virtual-cluster/#credential-mediation) on the virtual cluster.
+In that case, the client's OAuth bearer token is forwarded directly to the backend, and the backend cluster entity doesn't need to store separate credentials.
+
## Set up a backend cluster
{% entity_example %}
diff --git a/app/event-gateway/entities/virtual-cluster.md b/app/event-gateway/entities/virtual-cluster.md
index 811d103cdd5..4b34c848287 100644
--- a/app/event-gateway/entities/virtual-cluster.md
+++ b/app/event-gateway/entities/virtual-cluster.md
@@ -164,6 +164,8 @@ rows:
Requires clients to present a trusted TLS certificate during the TLS handshake.
The client certificate is verified against a [TLS trust bundle](/event-gateway/entities/tls-trust-bundle/).
The certificate's principal (for example, the Common Name) can be used to enforce access control with [ACL policies](/event-gateway/policies/acl/).
+
+ mTLS is also supported for the gateway-to-backend connection; configure it in the [backend cluster's TLS settings](/event-gateway/entities/backend-cluster/).
credential: None
{% endtable %}
@@ -175,9 +177,46 @@ and reuse existing credentials and principals defined on the backend cluster.
Use the virtual cluster `authentication.mediation` setting to configure a mediation mode.
Choose the mode based on your security requirements and backend cluster configuration:
-* Passthrough (`passthrough`): Authentication from the client passes through the proxy to the backend without validation. This method is required for SCRAM authentication.
-* Terminate (`terminate`): Checks whether the client’s connection is authorized based on their credential, and then terminates the authentication. Then, a new authentication session starts with the backend cluster.
-* Validate and forward (`validate_forward`): The client’s OAuth token is first validated by the proxy, and then sent to the backend as-is. This will “fail fast” if the token is invalid before sending it to the backend.
+
+{% table %}
+columns:
+ - title: Mode
+ key: mode
+ - title: How it works
+ key: how
+ - title: When to use
+ key: when
+rows:
+ - mode: "`passthrough`"
+ how: |
+ The client’s credentials pass through the proxy to the backend without validation.
+ when: |
+ The backend cluster natively supports the same auth mechanism the client uses (for example, SASL/OAUTHBEARER or SASL/SCRAM). Required for SCRAM authentication.
+ - mode: "`terminate`"
+ how: |
+ The proxy validates the client’s credential and terminates the auth session. It then opens a new, separate auth session with the backend using the credentials configured on the backend cluster entity.
+
+ When you use `terminate` mediation, the gateway-to-backend connection acts as a single service account, using the credentials configured on the backend cluster.
+ The backend Kafka cluster sees only that service account, not individual client principals.
+ Per-client authorization is enforced at the gateway layer using [ACL policies](#acl-mode) on the virtual cluster.
+ when: |
+ The backend cluster only supports username/password mechanisms (SASL/PLAIN or SASL/SCRAM) and clients authenticate with a different mechanism, such as OAuth.
+ - mode: "`validate_forward`"
+ how: |
+ The proxy validates the client’s OAuth token with the OAuth provider, then forwards the token to the backend as-is.
+ when: |
+ The backend cluster natively supports SASL/OAUTHBEARER. Use this instead of `passthrough` to fail fast on invalid tokens before they reach the backend.
+{% endtable %}
+
+
+### ACL mode
+
+The `acl_mode` field controls whether ACL policies are evaluated.
+When set to `enforce_on_gateway` (the default), clients start with no access to any resources on the virtual cluster.
+Operators grant access by adding ACL policies with principal-specific conditions.
+When set to `passthrough`, ACL policies are not evaluated and all authenticated clients have full access to whatever the backend cluster exposes.
+
+See [ACL policy](/event-gateway/policies/acl/) for details on defining access rules.
### Enrich connections with caller metadata
@@ -206,6 +245,10 @@ For example, a virtual cluster exposes a topic named `orders` to the client.
Behind the scenes, this maps to `team-a-orders` on the actual Kafka cluster. The client doesn't need to know about or manage the `team-a-` prefix.
This enables transparent multitenancy, where multiple teams can share the same Kafka cluster without needing to manually prefix every topic and consumer group name in their applications.
+When clients send fetch requests, the gateway passes the consumer group name to the backend unchanged, unless a namespace prefix is configured.
+Kafka handles consumer group coordination and offset tracking on the backend as normal.
+Consumer group management commands such as create and delete are intercepted by the gateway and evaluated against ACL policies using the `group` resource type.
+
The following examples provide some common use cases for namespaces and show how to set them up.
### Apply prefixes automatically