This page is meant as a template for writing a KIP. To create a KIP choose Tools->Copy on this page and modify with your content and replace the heading with the next KIP number and a description of your issue. Replace anything in italics with your own description.

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

KafkaPrincipal is formed from the name of the principal received from the underlying channel.

In the case of SSL, it is string representation of the X.500 certificate. By default, the user name associated
with an SSL connection looks like the following. "CN=writeuser,OU=Unknown,O=Unknown,L=Unknown,ST=Unknown,C=Unknown"

Often, users want to extract one of the field (e.g., CN) as the principal name. Currently in order to
customize SSL username a customized principal builder class is required. Having built-in
SSL principal builder configs/rules that allows to customize SSL principal name will be useful.

Public Interfaces

We are proposing the following options in the order of preference.

Option 1:

Add new configuration parameter pair of the form:

ssl.principal.mapping.pattern=^.*[Cc][Nn]=([a-zA-Z0-9.]*).*$
ssl.principal.mapping.value=$1

For the pattern portion of the pairing, regular expression syntax is used to parse the original identity into components.
The value portion of the pairing uses these parsed components in variable substitution format to build the translated version of the identity.

Above example, we only want to extract the CN part of the Subject and use it as the principal name of the client.
For the distinguished name "CN=userName, OU=OrgUnit, DC=Company", above pattern returns "userName" as the principal name.

This is a simple option and handles most of the common use cases.

Option 2:

Similar to SASL kerberos principal rules, we can have list of SSL principal mapping rules.

ssl.principal.mapping.rules: This config allows a list of rules for mapping distinguished certificate name to short principal name.
The rules are evaluated in order and the first rule that matches a principal name is used to map it to a short name.
Any later rules in the list are ignored. By default, string representation of the X.500 certificate will be the principal.

The possible values are:

RULE:exp The principal name will be formulated from exp.

The format for exp is pattern/replacement/[LU]. If the string matches the pattern, then the replacement
command will be run over the string.

Check below formats for syntax. Each rules starts with RULE: and contains an expression as the following formats.

RULE:pattern/replacement/
RULE:pattern/replacement/L

DEFAULT: string representation of the X.500 certificate will be the principal.

Similar to SASL kerberos principal rules, we can also support lowercase/upper case rule, to force
the result to be all lower/upper case. This is done by adding a "/L" , "/U" to the end of the rule.

Example:

ssl.principal.mapping.rules=RULE:^.*[Cc][Nn]=([a-zA-Z0-9.]*).*$/$1/,DEFAULT

This is option is more flexible and can handle more scenarios.

Proposed Changes

1. We will update DefaultKafkaPrincipalBuilder class to handle above proposed configuration options.
2. Proposed configuration will be applied to X500Principal distinguished name from the client certificate.
3. Proposed configuration will be ignored, if SSL client authentication is disabled. (In this case principal name is ANONYMOUS).
4. Proposed configuration will be ignored, if an extension of KafkaPrincipalBuilder is provided by the principal.builder.class configuration.

Compatibility, Deprecation, and Migration Plan

• There won't be any change of current behavior. By default, string representation of the X.500 certificate will be returned.

Rejected Alternatives