Status

Current state: "Under Discussion"

Discussion thread: here

JIRA: here

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

Kafka currently supports non-configurable SASL extensions in its SCRAM authentication protocol for delegation token validation. It would be useful to provide configurable SASL extensions for the OAuthBearer authentication mechanism as well, such that clients could attach arbitrary data for the principal authenticating into Kafka.

This way, a custom principal can hold information derived from the authentication mechanism, which could prove useful for better tracing and troubleshooting, for example. This can be done in a way which allows for easier extendability in future SASL mechanisms.

It is worth noting that these extensions would lack a digital signature and therefore should not be used for critical use-cases where security is a concern.

Public Interfaces

New config option for OAuthBearerLoginModule - `unsecuredLoginExtension_<extensionname>`. This will allow users to add custom extensions

`SaslExtensionsCallback` - generic callback to hold extensions

public class SaslExtensionsCallback implements Callback {
    /**
    * Returns a {@link SaslExtensions} consisting of the extension names and values that are sent by the client to
    * the server in the initial client SASL authentication message.
    */
    public SaslExtensions extensions()

    /**
     * Sets the SASL extensions on this callback.
     */
    public void extensions(SaslExtensions extensions)
}

`SaslExtensions` - class for holding extensions data

package org.apache.kafka.common.security.auth;

/**
 * A simple value object class holding customizable SASL extensions
 */
public class SaslExtensions {
    public SaslExtensions(Map<String, String> extensionMap)

    /**
     * Returns an <strong>immutable</strong> map of the extension names and their values
     */
     public Map<String, String> map() {
         return extensionsMap;
     }
}

Proposed Changes

Describe the new thing you want to do in appropriate detail. This may be fairly extensive and have large subsections of its own. Or it may be a few sentences. Use judgement based on the scope of the change.

Create a new `SaslExtensions` class that takes most of the generalizable logic from `ScramExtensions`. `ScramExtensions` will extend `SaslExtensions`
Create a new `SaslExtensionsCallback` which will be similar to `ScramExtensionsCallback`. `ScramExtensionsCallback` will NOT extend `SaslExtensionsCallback` since it will not support the new `SaslExtensions` class.
Pass `SaslExtensionsCallback` to the callback handler of `OAuthBearerLoginModule` so that the handler can parse the extensions from the JAAS config (unsecuredLoginExtension_xxx) and populate them in the Subject class.
Pass `SaslExtensionsCallback` to the callback handler of `OAuthBearerSaslClient` so that the handler can take the extensions from the Subject and populate them in the callback. `OAuthBearerSaslClient` will then attach the populated extensions (if any) to the first client message.
Have `OAuthBearerServer` parse sent extensions and expose them via its `OAuthBearerServer#getNegotiatedProperty()` method. It will use a strict regex, parsing only letters for keys and only ASCII characters for values

This will allow custom principals to access them through the `SaslServer` instance in `SaslAuthenticationContext#server()`

Example

A user would make use of the changes in this KIP in the following way:

1. Add the extension names to your JAAS configuration in the client
   
   

   KafkaClient {
       org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule Required
       unsecuredLoginStringClaim_sub="thePrincipalName"
   	unsecuredLoginExtension_traceId="123"
   	unsecuredLoginExtension_logLevel="WARN";
   };

2. A custom principal builder can then make use of the new extension

   1. public class CustomPrincipalBuilder implements KafkaPrincipalBuilder {
          @Override
          public KafkaPrincipal build(AuthenticationContext context) {
              if (context instanceof SaslAuthenticationContext) {
                  SaslServer saslServer = ((SaslAuthenticationContext) context).server();
                  String traceId = saslServer.getNegotiatedPropery("traceId");
                  return new CustomPrincipal("", saslServer, traceId);
              }
              throw new Exception();
          }
      }
      
      
      

Compatibility, Deprecation, and Migration Plan

• What impact (if any) will there be on existing users? None. This is simply allowing for more configuration. Other mechanisms like SCRAM should remain unaffected

Rejected Alternatives

• Add customizable extensions to every SASL client
  • | Not easily implementable, as we depend on a third-party library for PLAIN authentication
  • It is possible we implement configurable extensions for SCRAM as well. We would need to simply remove the checks in `ScramSaslServer` and then any custom callback handler could populate the extensions

As such, I decided it is best we limit the scope of this KIP while still implementing it in a way which would support future extensions by other SASL mechanisms