feat(event-gateway): Clarifications and more info on authentication for KEG

app/_event_gateway_policies/acl/index.md

@@ -100,6 +100,13 @@ sequenceDiagram
 {% endmermaid %}
 <!--vale on-->
 
+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.

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 %}

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/).
+      <br><br>
+      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.
+<!--vale off-->
+{% 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.
+      <br><br>
+      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 %}
+<!--vale on-->
+
+### 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