Kafka SSL principal mapping rules: readable names for ACLs

When Kafka authenticates a client by certificate, the principal name defaults to the full distinguished name, such as CN=writeuser,OU=Unknown,O=Unknown and so on. Set ssl.principal.mapping.rules on the broker to map that to a short name, then write ACLs against the short name.

The problem with the default name

The Kafka documentation says the default SSL user name is of the form CN, OU, O, L, ST and C joined together. If you wrote an ACL for that string, it would be long, easy to mistype and tied to every field of the certificate subject. A change in organisational unit would silently orphan your ACLs.

How the rules work

The mapping rules go in server.properties as a list. Each rule starts with RULE: and contains a pattern and a replacement. Rules are evaluated in order, and the first rule that matches the distinguished name is used. Later rules are ignored. A DEFAULT entry returns the full name.

The format is:

RULE:pattern/replacement/
RULE:pattern/replacement/[LU]

The optional L or U at the end forces the result to lower or upper case. Examples from the Kafka documentation include:

RULE:^CN=(.*?),OU=ServiceUsers.*$/$1/,
RULE:^CN=(.*?),OU=(.*?),O=(.*?),L=(.*?),ST=(.*?),C=(.*?)$/$1@$2/L,
RULE:^.*[Cc][Nn]=([a-zA-Z0-9.]*).*$/$1/L,
DEFAULT

Why order matters

Because the first match wins, put specific rules above general ones. A catch-all like the third example placed first would swallow everything, and your more careful rules would never run.

It also matters for security. A loose pattern can map two different certificates to the same short name, which means they share ACLs. Anchor patterns with the start and end markers, as the first example does, and constrain the organisational unit when you only want to accept certificates from a particular issuing group.

Keep the subject under control

The principal is only as trustworthy as who can get a certificate. The documentation notes that CA operators are often reluctant to copy requested extension fields from signing requests and prefer to set them themselves, because it makes it harder for a malicious party to obtain certificates with misleading values. If your CA signs whatever subject a requester asks for, a mapping rule cannot save you.

A safe workflow

1. Decide the principal naming scheme first, for example one short name per service.
2. Write the mapping rules to produce those names.
3. Create a test certificate for each pattern and verify the resulting principal, using broker logs or a test ACL.
4. Only then write ACLs against the short names. See least-privilege ACLs.
5. Review the rules whenever you change how certificates are issued.

Quick check

Sources

• Apache Kafka documentation: Authorization and ACLs
• Apache Kafka documentation: Encryption and authentication using SSL

Last reviewed: 19 October 2026.