This document outlines the security implications and risks of enabling client certificate forwarding in reverse proxies. These concerns are not exclusive to Envoy but apply to any reverse proxy that forwards client certificates. The initial architectural assumption is that all requests originate from the proxy, preventing direct client access to Keycloak. However, in environments like Kubernetes, some clients may bypass the proxy, leading to additional considerations.
The x-forwarded-client-cert (XFCC) header is used by Envoy proxy to send the client certificate information to the backend service, such as Keycloak.
When Envoy terminates an external TLS connection initiated by a client, it performs a TLS handshake.
During this handshake, the client can present a client certificate.
Envoy verifies that the client possesses the corresponding private key and validates the certificate.
After successful validation, Envoy forwards the certificate to the backend service via the XFCC header.
Keycloak then uses the certificate for authorization purposes in the X509 client certificate authenticator or other components, such as OAuth 2.0 Mutual TLS Certificate Bound Access Tokens.
Pre-conditions:
- Keycloak is configured with the X509 Client Certificate Lookup for Envoy.
- A client is created in Keycloak with "X509 client certificate" client authenticator enabled.
- A client running inside Kubernetes cluster connects to Keycloak directly, without going through the Envoy proxy, using mutually authenticated TLS.
Scenario:
Authentication fails because X509 Client Certificate Lookup for Envoy expects the identity from the XFCC header, which is not set for internal clients. The client certificate information from the TLS layer is not used.
Pre-conditions:
- Keycloak is configured with the X509 Client Certificate Lookup for Envoy.
- A client is created in Keycloak with "X509 client certificate" client authenticator enabled.
- A malicious user has acquired (1) the client ID and (2) the subject name of the client certificate.
- A Malicious user has gained access to the cluster e.g., through a compromised pod.
Scenario:
A malicious client within the cluster uses a forged certificate in the XFCC header to impersonate a client identity without proving possession of the private key associated with a legitimate client certificate. This can include a Keycloak admin client to obtain full access to Keycloak. The forged certificate can be self-generated by the malicious user, as long as it contains the correct subject name.
The following example diagram demonstrates the logic implemented by the X509 Client Certificate Lookup for Envoy for authorizing the use of XFCC headers. This mechanism is designed to accept client certificates forwarded by the Envoy proxy in XFCC header, while also securely handling clients that bypass the proxy and connect directly to Keycloak. These direct clients are authenticated and authorized using their TLS-level client certificates or other authenticators (e.g. client secret) and are prevented from impersonating other clients by sending unauthorized XFCC headers.
For this mitigation to be effective, Envoy must be configured to use TLS and client certificate authentication for its connection to Keycloak. Additionally, X509 Client Certificate Lookup for Envoy must be configured with the expected client certificate subject names for Envoy proxy.
