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