About this guide

This guide covers using the Kroxylicious SASL Inspection Filter. This filter extracts the authenticated principal from a successful SASL exchange between Kafka Client and Kafka Broker and makes it available to the other filters in the chain.

Refer to other Kroxylicious guides for information on running the proxy or for advanced topics such as plugin development.

This filter inspects the SASL exchange between Kafka Client and Broker and extracts the authenticated principal. If the client’s authentication with the broker is successful, the filter makes the authenticated principal available to the other filters in the chain, so that they may know on whose behalf they are acting.

The SASL Inspection Filter plays no part in deciding if the authentication is successful or not. That role remains the exclusive responsibility of the broker.

To use this filter, the Kafka Cluster’s listener must be configured to authenticate using SASL, and it must use a SASL mechanism that enabled by this filter. If the Kafka Client is configured to use a SASL mechanism that is not supported by the proxy, or the proxy and Kafka Cluster do not have the same mechanism available the client will be disconnected with an unsupported SASL mechanism error.

This filter supports the following SASL mechanisms:

Table 1. Table of supported SASL mechanisms
SASL mechanism Enabled by default

PLAIN

No

SCRAM-SHA-256

Yes

SCRAM-SHA-512

Yes

OAUTHBEARER

Yes

Mechanisms that transmit credentials in plain text are disabled by default. This is done to avoid the plain-text passwords existing in the proxy’s memory. To use such a mechanism, you must enable it in the filter’s configuration.

For the OAUTHBEARER inspection, only JWT tokens that use using signatures (JWS) are supported. JWT tokens that use encryption (JWE) are not supported. Unsigned JWT tokens are supported but not recommended for production use.

If an attempted is made to use a unsupported token type, the authentication will fail with a SASL error.

Sequence diagram showing SASL inspection.
Figure 1. Sequence diagram showing the SASL inspection filter extracting an authenticated principal from an SASL negotiation.

1. Configuring the SASL inspection filter

This procedure describes how to set up the SASL Inspection Filter by configuring it in Kroxylicious.

Prerequisites
Procedure

  1. Configure a SaslInspection type filter.

1.1. Example proxy configuration file

If your instance of the Kroxylicious Proxy runs directly on an operating system, provide the filter configuration in the filterDefinitions list of your proxy configuration.

Here’s a complete example of a filterDefinitions entry configured for Oauth Bearer validation:

Example filterDefinitions configuration 
filterDefinitions:
  - name: my-sasl-inspection-filter
    type: SaslInspection
    config:
      enabledMechanisms: [ "OAUTHBEARER" ] (1)
1 Restricts the filter to the given SASL mechanism(s). Refer to SASL mechanism by its name given in the supported mechanisms table. If omitted, the SASL mechanisms SCRAM-SHA-256, SCRAM-SHA-512 and OAUTHBEARER will be enabled by default.

Refer to the Kroxylicious Proxy guide for more information about configuring the proxy.

1.2. Example KafkaProtocolFilter resource

If your instance of Kroxylicious runs on Kubernetes, you must use a KafkaProcotolFilter resource to contain the filter configuration.

Here’s a complete example of a KafkaProtocolFilter resource configured for Oauth Bearer validation:

Example KafkaProtocolFilter resource for record validation 
kind: KafkaProtocolFilter
metadata:
  name: my-sasl-inspection-filter
spec:
  type: SaslInspection
  configTemplate:
      enabledMechanisms: [ "OAUTHBEARER" ] (1)
1 Restricts the filter to the given SASL mechanism(s). Refer to SASL mechanism by its name given in the supported mechanisms table. If omitted, the SASL mechanisms SCRAM-SHA-256, SCRAM-SHA-512 and OAUTHBEARER will be enabled by default.

Refer to the Kroxylicious Operator for Kubernetes guide for more information about configuration on Kubernetes.

2. Trademark notice

  • Apache Kafka is a registered trademark of The Apache Software Foundation.

  • Kubernetes is a registered trademark of The Linux Foundation.

  • Prometheus is a registered trademark of The Linux Foundation.

  • Strimzi is a trademark of The Linux Foundation.

  • Hashicorp Vault is a registered trademark of HashiCorp, Inc.

  • AWS Key Management Service is a trademark of Amazon.com, Inc. or its affiliates.

  • Fortanix and Data Security Manager are trademarks of Fortanix, Inc.

3. Glossary

Glossary of terms used in the SASL Inspection guide.

JWE

JSON Web Encryption is an IETF standard for exchanging encrypted data using JSON.

JWT

JSON Web Token is an IETF standard for securely transmitting information between parties as a JSON object.

JWS

JSON Web Signature is an IETF-proposed standard for signing arbitrary data.

SASL

Simple Authentication and Security Layer, a framework for handling authentication.