Use CEL Filters for mTLS Authentication on Confluent Cloud

You can create fine-grained access control for mTLS authentication by specifying identity pool filters in the certificate identity pools you use for your applications and workloads. To specify access, Confluent Cloud supports the following specification based on Common Expression Language (CEL). Unlike OAuth JWT claims, CEL filters for mTLS authentication have a supported set of X.509 certificate metadata that can be used in the filter expression.

Rules for CEL filters

  • All identifiers (left-hand side LHS) and values (right-hand side RHS) are case-sensitive matching.
  • RHS values are either expressions, string values as defined in CEL, or a list of string values.
  • Allowed operators, for conditional operators, the lower the precedence value the higher the evaluation order.
Operator CEL expression
Equality (==) identifier == "Confluent"
Inequality (!=) identifier != "Confluent"
Inclusion (in) identifier in ["Confluent", "Kafka"]
Prefix matching (.startsWith()) identifier.startsWith("Confluent")
Suffix matching (.endsWith()) identifier.endsWith("Confluent")
Substring matching (.contains()) identifier.contains("Confluent")
Operator Operator precedence CEL expression
Logical NOT (!) 1 !(identifier == "Kafka")
Logical AND (&&) 2 (identifier == "Kafka") && (identifier == "Confluent")
Logical OR (||) 3 (identifier == "Kafka") || (identifier == "Confluent")
  • Rules can be grouped into parentheses, like this: Expression && ( Expression || Expression ), parenthesized expressions are higher evaluation priority than others.
  • If the filter is empty, then the evaluation returns false.

Defined identifiers for certificate metadata

Subject Distinguished Name (DN) part matching

The attribute names listed below are permissible as identifiers in Distinguished Names (DNs), adhering to RFC 4514.

Attribute name or identifier Meaning Data type
DC domainComponent string
CN commonName string
OU organizationalUnitName string
O organizationName string
STREET streetAddress string
L localityName string
ST stateOrProvinceName string
C countryName string
UID userid string

Only the first occurrence of each attribute is considered for matching. To match against repeated attributes within a DN, use string matching techniques for the DN identifier.

Examples

O.contains("Confluent")

For attribute values, the string representation must follow RFC 2253 format. For example, the value “Confluent, Inc.” is represented as Confluent\, Inc. because , is a reserved character, and the expression to match this in CEL is as follows (r/R prefix means raw string in CEL and \ is the escape character).

O==r"Confluent\, Inc."

Recommendations

  • Avoid using reserved characters (escaped characters) as much as possible because they can cause undesirable outcomes because of escaped characters. For more details on reserved characters, see Reserved characters in DN attribute value. If you need to use reserved characters, then you can use raw strings in the filter.
  • Multi-valued attribute (multi-valued RDN) part matching is unsupported. For example, if you have a component OU=Sales+CN=J.Smith in the DNI, then only the OU=Sales component is recognized for part matching, and anything after that (starting with the + part) is ignored. In order to use multi-valued attribute, you can use string matching for DN identifier.

Subject Distinguished Name (DN) matching

Identifier Meaning Data type Representation format
DN Distinguished name string RFC 2253. For example, CN=confluent.io,OU=Kafka\, Cloud,O=Confluent,L=Mountain View\, 899 W Evelyn Ave,ST=California,C=US.

DN is used as the identifier for matching subject name of the certificate.

Examples

DN.contains("CN=Confluent")

DN.contains("OU=Sales+CN=J.Smith")

Recommendations

  • Equality matching of DN is discouraged because of the ambiguity of the order of components. Substring matching is recommended, or use part matching.
  • Use uppercase attribute names as defined in RFC 2253.
  • To use quality matching, you must use the string output from the following keytool command:
keytool -printcert -file certificate.pem

Subject Alternative Name (SAN) matching

Identifier Meaning Data type Representation format
SAN Subject Alternative Name string Comma-separated list of GeneralName:Value pairs. For example, DNS:confluent.io,IP:10.10.10.10

Here are the general names that are supported:

General Name Meaning Example string representation
OTHERNAME Other name OTHERNAME:Other name
EMAIL Email EMAIL:myemail@confluent.io
DNS Domain name DNS:*.confluent.io
X400 X400 X400:G=Harald;S=Alvestrand;O=Uninett;PRMD=Uninett;A=;C=no
DIR Directory name DIR:value
EDIPARTY Electronic Data Interchange (EDI) Party Name EDIPARTY:value
URI Uniform Resource Identifier URI:crn://abc.com
IP IP addresses

IPv4: IP:127.0.0.1

IPv6: IP:2001:0:130f:0:0:9c0:876a:130b. Must be in lowercase hexadecimal format, defined in RFC 5280.
RID Registered ID RID:value

Examples

SAN.contains("DNS:*.confluent.io")

SAN.contains("EMAIL:myemail@confluent.io")

SAN.contains("IP:127.0.0")

SAN.contains("IP:2001:0:130f:0:0:9c0:876a:130b")

Recommendations

  • Use the General Names in bold text for SAN matching.
  • All General Names must be in uppercase value as defined in RFC 5280.
  • Equality matching of SAN is discouraged because there is no defined order for General Names, and they can be repeated.
  • Substring matching is recommended.

Certificate serial number matching

Identifier Meaning Data type Representation format
SNID Serial number identifier string Hexadecimal number with numbers (0-9) and uppercase letters (A-F). For example, 00D3B9E2C1CC02971E.

Examples

SNID == "00D3B9E2C1CC02971E"

SHA-1 fingerprint matching

Identifier Meaning Data type Representation format
SHA1 SHA-1 fingerprint of the certificate string Hexadecimal number with numbers (0-9) and uppercase letters (A-F). For example, B9FB79AF4E292DB85DCBDF769EE47F3F0B69A110.

Examples

SHA1.endsWith("5CB039D4329A5E8")

The fingerprint is calculated using the following formula:

SHA-1(CERTIFICATE file in DER format)

For example, on macOS, the following shalsum command should work with a certificate file in DER format:

shalsum <cert.der>

To check if your SHA-1 fingerprint is calculated correctly, you can verify if your calculation of Let’s Encrypt ISRG root X1 matches the fingerprint defined here:

CABD2A79A1076A31F21D253635CB039D4329A5E8

Appendix

Reserved characters in DN attribute value

The following table lists reserved characters that cannot be used in an attribute value without being escaped.

Reserved character Description Hex value
`` # `` or leading `` ` ` `` space or # character at the beginning of a string  
trailing `` ` ` `` space character at the end of a string  
, comma 0x2C
+ plus sign 0x2B
" double quote 0x22
\ backslash 0x5C
< left angle bracket 0x3C
> right angle bracket 0x3E
; semicolon 0x3B
LF line feed 0x0A
CR carriage return 0x0D
= equals sign 0x3D
/ forwards slash 0x2F

If a reserved character is part of an attribute value, it must be escaped by prefixing it with a backslash (\) in the attribute string. If an attribute value contains other reserved characters, such as the equals sign (=) or non-printable characters, it must be encoded in hexadecimal by replacing the character with a backslash followed by two hexadecimal digits.

Examples

Here are some examples of some Distinguished Names that include escaped characters.

The first example is an organizational unit name with an embedded comma.

CN=Litware,OU=Docs\, Adatum,DC=Fabrikam,DC=COM

The second example is a value containing a carriage return.

CN=Before\0DAfter,OU=Test,DC=North America,DC=Fabrikam,DC=COM

Related content