<a id="tls-principal-mapping"></a>

# 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 a 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`
  <br/>
  `listener.name.internal.ssl.principal.mapping.rules`

TLS authentication
: For details, see [TLS principal user name](../../authorization/acls/overview.md#tls-principal-name)

Access control lists (ACLs)
: Uses the same `ssl.principal.mapping.rules` as mTLS authentication.

Role-based access control (RBAC)
: `confluent.metadata.server.auth.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](../../../kafka/post-deployment.md#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 your Confluent Platform cluster, the Distinguished Name (DN) in the TLS certificate
is used for authentication. The `ssl.principal.mapping.rules` property is 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 your 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:

```properties
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 following formats.

The default rule returns the 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 backslashes, 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 by
  adding an `/L` or `/U` to the end of the rule:
  ```bash
  RULE:pattern/replacement/
  RULE:pattern/replacement/[LU]
  ```

Example `ssl.principal.mapping.rules` values are:

```bash
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`.