About this guide

This guide covers using the Kroxylicious Oauth Bearer Validation Filter. This filters validates the JWT token received from client before forwarding it to cluster. Refer to other Kroxylicious guides for information on running the proxy or for advanced topics such as plugin development.

OauthBearerValidation filter enables a validation on the JWT token received from client before forwarding it to cluster.

If the token is not validated, then the request is short-circuited. It reduces resource consumption on the cluster when a client sends too many invalid SASL requests.

Sequence diagram showing the filter validating the oauth token before it reaches the broker.
Figure 1. Sequence diagram showing the filter validating the oauth token before it reaches the broker.

1. Configuring the Oauth Bearer valudation filter

This procedure describes how to set up the Oauth Bearer Validation filter by configuring it in Kroxylicious.

Prerequisites
Procedure

  1. Configure a OauthBearerValidation type filter.

Note: OauthBearer config follows kafka’s properties

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-oauth-filter
    type: OauthBearerValidation
    config:
      jwksEndpointUrl: https://oauth/JWKS   (1)
      jwksEndpointRefreshMs: 3600000        (2)
      jwksEndpointRetryBackoffMs: 100       (3)
      jwksEndpointRetryBackoffMaxMs: 10000  (4)
      scopeClaimName: scope                 (5)
      subClaimName: sub                     (6)
      authenticateBackOffMaxMs: 60000       (7)
      authenticateCacheMaxSize: 1000        (8)
      expectedAudience: https://first.audience, https//second.audience (9)
      expectedIssuer: https://your-domain.auth/ (10)
1 The OAuth/OIDC provider URL from which the provider’s JWKS (JSON Web Key Set) can be retrieved.
2 The (optional) value in milliseconds for the broker to wait between refreshing its JWKS (JSON Web Key Set) cache that contains the keys to verify the signature of the JWT.
3 The (optional) value in milliseconds for the initial wait between JWKS (JSON Web Key Set) retrieval attempts from the external authentication provider.
4 The (optional) value in milliseconds for the maximum wait between attempts to retrieve the JWKS (JSON Web Key Set) from the external authentication provider.
5 This (optional) setting can provide a different name to use for the scope included in the JWT payload’s claims.
6 This (optional) setting can provide a different name to use for the subject included in the JWT payload’s claims.
7 The (optional) maximum value in milliseconds to limit the client sending authenticate request. Setting 0 will never limit the client. Otherwise, an exponential delay is added to each authenticate request until the authenticateBackOffMaxMs has been reached.
8 The (optional) maximum number of failed tokens kept in cache.
9 The (optional) comma-delimited setting for the broker to use to verify that the JWT was issued for one of the expected audiences.
10 The (optional) setting for the broker to use to verify that the JWT was created by the expected issuer.

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-oauth-bearer-validation-filter
spec:
  type: OauthBearerValidation
  configTemplate:
      jwksEndpointUrl: https://oauth/JWKS   (1)
      jwksEndpointRefreshMs: 3600000        (2)
      jwksEndpointRetryBackoffMs: 100       (3)
      jwksEndpointRetryBackoffMaxMs: 10000  (4)
      scopeClaimName: scope                 (5)
      subClaimName: sub                     (6)
      authenticateBackOffMaxMs: 60000       (7)
      authenticateCacheMaxSize: 1000        (8)
      expectedAudience: https://first.audience, https//second.audience (9)
      expectedIssuer: https://your-domain.auth/ (10)
1 The OAuth/OIDC provider URL from which the provider’s JWKS (JSON Web Key Set) can be retrieved.
2 The (optional) value in milliseconds for the broker to wait between refreshing its JWKS (JSON Web Key Set) cache that contains the keys to verify the signature of the JWT.
3 The (optional) value in milliseconds for the initial wait between JWKS (JSON Web Key Set) retrieval attempts from the external authentication provider.
4 The (optional) value in milliseconds for the maximum wait between attempts to retrieve the JWKS (JSON Web Key Set) from the external authentication provider.
5 This (optional) setting can provide a different name to use for the scope included in the JWT payload’s claims.
6 This (optional) setting can provide a different name to use for the subject included in the JWT payload’s claims.
7 The (optional) maximum value in milliseconds to limit the client sending authenticate request. Setting 0 will never limit the client. Otherwise, an exponential delay is added to each authenticate request until the authenticateBackOffMaxMs has been reached.
8 The (optional) maximum number of failed tokens kept in cache.
9 The (optional) comma-delimited setting for the broker to use to verify that the JWT was issued for one of the expected audiences.
10 The (optional) setting for the broker to use to verify that the JWT was created by the expected issuer.

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.