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 theOU=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.
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: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: IPv6: |
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")
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