Confluent Developer Marketplace Get started
  1. Home
  2. Platform
  3. Security in Confluent Platform
  4. Authentication in Confluent Platform
  5. Mutual TLS Authentication in Confluent Platform

Use Principal Mapping in Confluent Platform

Principal mapping transforms long or complex identities from Transport Layer Security (TLS) certificates into short, user-friendly principal names in Confluent Platform. When a client connects, Confluent Platform extracts the identity from the certificate and applies mapping rules to produce a principal that represents a user or service account for authentication, authorization, and quota enforcement.

Uses for mapped principals

  • Access control lists (ACLs) and role-based access control (RBAC): Enforces permissions using the shortened principal name instead of the raw certificate string.

  • Client quotas: Enforces client quotas on the mapped principal identity.

  • Simplified certificate management: Allows managing client permissions by mapped identity rather than tracking individual certificates.

  • External system integration: Maps certificate identities directly to user accounts or service roles in external identity providers.

Mapping a certificate to a principal involves three steps:

  1. Identify whether the certificate source is the Subject DN or the SAN URI.

  2. Define mapping rules using RULE: or SANURIRULE: syntax. For details, see Principal mapping rules format.

  3. Apply the rules to your component configuration. For details, see Configure principal mapping rules per component.

Before configuring principal mapping, set up mutual TLS (mTLS) authentication as described in Use TLS Authentication in Confluent Platform.

Distinguished Name (DN) attributes

A Distinguished Name (DN) is a sequence of X.500 attributes that uniquely identifies the subject of a TLS certificate.

Example DN:

CN=writeuser,OU=Engineering,O=Confluent,L=Palo Alto,ST=CA,C=US

When parsing a DN, Confluent Platform evaluates X.500 attributes in the following order:

Key

Attribute name (X.520)

Example value

CN

commonName

writeuser

OU

organizationalUnitName

Engineering

O

organizationName

Confluent

L

localityName

Palo Alto

ST

stateOrProvinceName

CA

C

countryName

US

You can add custom DN mapping rules to the ssl.principal.mapping.rules property in your component configuration files. For example, broker.properties, controller.properties, or server.properties. For rule syntax, see Principal mapping rules format.

Rules are evaluated in order. The first rule that matches a DN maps the principal, and Confluent Platform ignores later rules.

Subject Alternative Name (SAN) URI

A Subject Alternative Name (SAN) is a certificate extension that specifies more identities for the subject. While SAN extensions can contain Domain Name System (DNS) names or Internet Protocol (IP) addresses, Confluent Platform principal mapping specifically supports URI-type SAN entries.

Example SAN URI entry:

URI:aprn:myorg:certmgr:::person-v2:/pid/123456/uv/

Use a SAN URI as the identity source when:

  • The certificate’s Subject DN doesn’t contain a usable identity.

  • Your organization formats client identities as URIs, such as Amazon Resource Names (ARNs), SPIFFE (Secure Production Identity Framework For Everyone) IDs, or custom URI schemes.

A certificate can contain zero, one, or multiple URI SAN entries. Confluent Platform extracts all URI SAN entries from the leaf certificate and evaluates your SANURIRULE: expressions against each entry, in order, until one matches. For rule syntax, see Principal mapping rules format. Blank or malformed entries are ignored.

Note

Only URI-type SAN entries with GeneralName type 6 are supported. Other SAN types are not read for principal mapping. This includes DNS names, IP addresses, and otherName entries such as SPIFFE or X.509-SVID identifiers.

Principal mapping rules format

Specify mapping rules as a comma-separated list in ssl.principal.mapping.rules. Each rule starts with a tag indicating which part of the certificate it targets:

  • RULE: matches against the Subject DN. This is the default rule type. Untagged rules and DEFAULT target the Subject DN, preserving backward compatibility for existing configurations.

  • SANURIRULE: matches against a URI-type SAN entry. Use this tag to map identities stored in the certificate’s SAN extension instead of its Subject DN.

Both rule types share the same syntax, and you can mix RULE: and SANURIRULE: entries in the same property value. Each rule type is only tested against matching candidate strings. SANURIRULE: is never tested against a Subject DN, and RULE: is never tested against a SAN URI.

Principal mapping rule syntax

A rule follows the format: TAG:pattern/replacement/[LU]

  • Shorthand character classes: Use double backslashes for shorthand character classes. For example, \\d for digits, \\w for word characters, \\s for whitespace, and \\p{L} for Unicode letters.

  • Escaping special characters: Escape special characters in regular expressions with an extra backslash. For example, \\. for a literal dot.

  • Escaping forward slashes: Because / delimits the rule sections, escape literal forward slashes in patterns:

    • ``.properties`` files: Use a double backslash. For example, https:\\/.

    • YAML files: Use a single backslash for components such as Flink and Confluent Manager for Apache Flink. For example, https:\/.

  • Case conversion: Append /U or /L to the end of the rule to force the output to uppercase or lowercase.

Example rules:

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 following DNs into mapped principals:

Certificate DN

Mapped principal

CN=serviceuser,OU=ServiceUsers,O=Unknown,L=Unknown,ST=Unknown,C=Unknown

serviceuser

CN=adminUser,OU=Admin,O=Unknown,L=Unknown,ST=Unknown,C=Unknown

adminuser@admin

Rule evaluation order for mixed rule types

Confluent Platform evaluates rules strictly in the order listed. The first matching rule of either type wins, even when a certificate contains both a Subject DN and one or more SAN URIs as candidate strings.

To order a mixed list of rules, follow these guidelines:

  • List specific rules first: Place narrow, explicit regular expressions before broader ones.

  • Order by preferred source: If you prefer SAN URIs over Subject DNs when both exist, list all SANURIRULE: entries before your RULE: entries.

  • Include a fallback rule: End rule lists with a fallback, such as DEFAULT for Subject DN or a catch-all SANURIRULE:, so unmatched certificates map predictably rather than failing authentication.

SAN URI mapping rule examples

The following examples show how SAN URI mapping rules extract a principal from different certificate SAN entry formats. The URI: prefix in the “Certificate SAN entry” column is a display label, not part of the value. SANURIRULE: patterns match the URI value alone, without that prefix.

Rule

Certificate SAN entry

Extracted principal

SANURIRULE:^aprn:myorg:certmgr:::person-v2:\\/pid\\/(\\d+)\\/uv\\/$/$1/

URI:aprn:myorg:certmgr:::person-v2:/pid/123456/uv/

123456

SANURIRULE:^arn:aws:iam::\\d+:role\\/(.+)$/$1/

URI:arn:aws:iam::123456789012:role/PaymentsServiceRole

PaymentsServiceRole

SANURIRULE:^https:\\/\\/api\\.github\\.com\\/repos\\/([^\\/]+)\\/([^\\/]+)\\/issues.*$/$1-$2/

URI:https://api.github.com/repos/confluentinc/ce-kafka/issues?state=open

confluentinc-ce-kafka

SANURIRULE:^https:\\/\\/([^:]+):[^@]+@.*$/$1/

URI:https://alice:pass@confluent.io:8443/api/v1/users?id=42&active=true#profile-section

alice

Configure principal mapping rules per component

Set principal mapping rules using the appropriate property for each component or feature:

Component or feature

Configuration property

mTLS per listener

listener.name.<listener-name>.ssl.principal.mapping.rules

RBAC, through Metadata Service (MDS)

confluent.metadata.server.auth.ssl.principal.mapping.rules

Confluent Schema Registry

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

Confluent REST Proxy

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

To set default rules for all listeners on a broker, configure ssl.principal.mapping.rules in the broker configuration files, such as server.properties.

All listed components support Subject DN mapping. To view components that support SAN URI mapping, see SAN URI mapping support by component.

SAN URI mapping support by component

SAN URI mapping (SANURIRULE:) works on all Confluent Platform components that authenticate clients using mTLS:

  • Apache Kafka® broker

  • Schema Registry

  • Confluent REST Proxy

  • Kafka Connect

  • ksqlDB

  • Metadata Service (MDS)

  • Apache Flink®, through Confluent Manager for Apache Flink

Note

SAN URI mapping only applies to certificate-based mTLS authentication and has no effect on non-certificate authentication mechanisms such as OAuth/OpenID Connect (OIDC) or the Lightweight Directory Access Protocol (LDAP).

Security considerations for SAN URI principal mapping

  • Truststore governance: A SAN URI is only as trustworthy as the certificate authority (CA) that issued it. Enable SANURIRULE: mapping only on listeners or components whose truststore you control and trust.

  • Fail-closed processing: If a SAN entry is malformed or unparsable, Confluent Platform drops the entry rather than assigning an unverified identity.

  • Log sanitization: Confluent Platform sanitizes SAN values before writing them to logs to prevent log injection.