Use Principal Mapping in Confluent Platform

You can use principal mapping in Confluent Platform to map the X.500 distinguished name (DN) from a TLS certificate to the Confluent Platform principal. A distinguished name is the concatenation of the X.500 attributes that uniquely identify the subject of a TLS certificate. The DN contains information about the entity (such as a person or organization) to which the certificate was issued.

X.509 public-key certificates, which contain the DNs of the issuers, are used in the following security-related features in Confluent Platform. You can use principal mapping to map the DNs to a much shorter and user-friendly name, which you can use as the identity for the client in Confluent Platform authentication and authorization.

Principal mapping rules in Confluent Platform

In Confluent Platform, TLS principal mapping can be specified using the following configuration settings:

Mutual TLS (mTLS) authentication

listener.name.external.ssl.principal.mapping.rules

listener.name.internal.ssl.principal.mapping.rules

TLS authentication

For details, see TLS principal user name

Access control lists (ACLs)

acl.ssl.principal.mapping.rules

Role-based access control (RBAC)

rbac.ssl.principal.mapping.rules

Confluent Schema Registry

confluent.schema.registry.auth.ssl.principal.mapping.rules

Confluent Control Center

confluent.controlcenter.auth.ssl.principal.mapping.rules

Confluent REST Proxy

confluent.rest.auth.ssl.principal.mapping.rules

Client quotas

To enforce client quotas on the mapped principal.

The rules are typically set in the Confluent Server broker configuration files and are specified in the ssl.principal.mapping.rules property. These rules affect how TLS connections are authenticated and authorized in Confluent Platform. When a client connects to the Confluent Platform cluster, the Distinguished Name (DN) in the TLS certificate is used for authentication. The ssl.principal.mapping.rules property are used to transform the DN into a much shorter and user-friendly name for the principal, which you can use as the identity for the client in Confluent Platform authentication and authorization.

• Access control lists (ACLs): The mapped principal is used to enforce access control on the mapped principal.
• Role-based access control (RBAC): The mapped principal is used to enforce role-based access control on the mapped principal.
• Simplifying certificate management: The mapped principal is used to simplify certificate management by allowing you to manage certificates for the mapped principal instead of managing certificates for each client.
• Integration with other systems: The mapped principal is used to integrate Confluent Platform mapped principals with identities in other systems.

By using principal mapping, you can simplify the process of managing TLS certificates and integrating Confluent Platform with other systems. You can dynamically change the principal mapping rules to change the way principals are mapped, without requiring a restart of the Confluent Platform cluster.

Distinguished Name (DN) attributes

A distinguished name (DN) is the concatenation of the X.500 attributes that uniquely identify the subject of a TLS certificate. Here’s an example of a DN:

CN=writeuser,OU=Unknown,O=Unknown,L=Unknown,ST=Unknown,C=Unknown

The following table shows the X.500 Distinguished Name (DN) attributes and their corresponding keys, listed in the order they are evaluated.

Key	Attribute (X.520 keys)
CN	commonName
OU	organizationalUnitName
O	organizationName
L	localityName
ST	stateOrProvinceName
C	countryName

This configuration allows a list of rules for mapping the X.500 distinguished name (DN) to short name. You can create a custom rule for your use case by adding a new rule to the ssl.principal.mapping.rules property in the Confluent Server broker configuration files (for example, broker.properties, controller.properties, and server.properties).

The rules are evaluated in order and the first rule that matches a DN is used to map it to a short name. Any other rules later in the list are ignored.

Principal mapping rules format

The format of ssl.principal.mapping.rules is a list where each rule starts with RULE: and contains an expression using the formats below.

The default rule returns string representation of the X.500 certificate DN. If the DN matches the pattern, then the replacement command is run over the name.

• Shorthand character classes are supported using double backslahes, for example, \\d for digits, \\w for word characters, \\s for whitespace, and \\p{L} for Unicode letters.

• To use a backslash (\) in the pattern or replacement, escape it with an additional backslash (\\). For example, to match a dot (.), use \\..

• To remove the CN= portion of the DN, you can use a rule like RULE:^CN=(.*?)$/$1/.

• You can force the translated result to be all lowercase or uppercase case by adding an /L or /U to the end of the rule:

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

Example ssl.principal.mapping.rules values are:

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

These rules translate the DN as follows: CN=serviceuser,OU=ServiceUsers,O=Unknown,L=Unknown,ST=Unknown,C=Unknown to serviceuser and CN=adminUser,OU=Admin,O=Unknown,L=Unknown,ST=Unknown,C=Unknown to adminuser@admin.