Client certificate identity filters
Client certificate identity filters admit connections only from specific client
identities. The load balancer applies the filters after trust-store validation passes,
and runs revocation checks after a certificate matches a filter. You configure filters in the
ClientCertificateIdentityFilters property of
MutualAuthenticationAttributes.
Filters are optional. If you do not configure any filter, the load balancer admits every client certificate that passes trust-store validation and revocation checks.
Each filter rule matches a field in the client certificate. You can match the following fields.
-
subject-cn– the common name in the certificate subject. -
subject-ou– the organizational unit in the certificate subject. -
san-dns– a DNS name in the subject alternative name (SAN). -
san-uri– a URI in the subject alternative name (SAN).
Each filter rule uses the accept action, which is the only supported
action. Because the only action is accept, the load balancer rejects a
certificate that does not match at least one filter rule. If the filter list is empty,
the load balancer applies no filtering, so every trust-store-valid certificate
passes.
If a client certificate does not contain a field that a filter references (for example, no SAN extension, or no organizational unit in the subject), that filter does not match. If no other filter matches, the load balancer rejects the connection. For a field that has multiple values (for example, multiple organizational units in the subject, or multiple DNS names in the SAN), a filter matches if it matches any one of the values.
When the load balancer rejects a connection because the certificate matched no filter,
it records CertificateFilterNoMatch in the access log
tls_verify_status field. For more information, see Error reason codes.
Each filter rule uses a match type of exact or prefix, and a
value of 1–256 printable ASCII characters. The load balancer combines rules with OR logic, so it
admits a connection if the certificate matches at least one rule. You can configure up
to 100 filter rules per listener.
The following case rules apply to both the exact and
prefix match types:
-
For the
subject-cn,subject-ou, andsan-dnsfields, matching is case-insensitive. -
For the
san-urifield, the scheme and host are matched case-insensitively, and the rest of the URI, such as the path, is matched case-sensitively. For example, a filter value ofSPIFFE://EXAMPLE.COM/workloadmatchesspiffe://example.com/workload, but does not matchspiffe://example.com/Workload.
The san-uri field requires values in URI format. In addition to the
general value rules, a san-uri value must meet the following
requirements:
-
The value must begin with a letter.
-
Before the first colon, the value can contain only letters, digits, plus signs (
+), hyphens (-), or periods (.). This part is the URI scheme. -
If the match type is
exact, the value must contain a colon.
For example, spiffe://example.com/workload is a valid value. The load
balancer rejects values such as 1spiffe://example.com (begins with a
digit), spiffe_id://example.com (contains an underscore before the
colon), or an exact value that contains no colon.
Configure client certificate identity filters
You add client certificate identity filters to a TLS listener that already uses mTLS in verify mode.