Update docs with security warning around client certificate lookup

Closes keycloak#35217 Signed-off-by: Václav Muzikář <[email protected]>
vmuzikar · Nov 22, 2024 · 979c5e1 · 979c5e1
1 parent 05116f7
commit 979c5e1
Show file tree

Hide file tree

Showing 3 changed files with 24 additions and 0 deletions.
diff --git a/docs/documentation/release_notes/topics/26_0_6.adoc b/docs/documentation/release_notes/topics/26_0_6.adoc
@@ -0,0 +1,6 @@
+= Updates to documentation of X.509 client certificate lookup via proxy
+
+Potential vulnerable configurations have been identified in the X.509 client certificate lookup when using a reverse proxy.
+Additional configuration steps might be required depending on your current configuration. Make sure to review the updated
+link:{client_certificate_lookup_link}[reverse proxy guide] if you have configured
+the client certificate lookup via a proxy header.
diff --git a/docs/documentation/topics/templates/document-attributes.adoc b/docs/documentation/topics/templates/document-attributes.adoc
@@ -56,6 +56,7 @@
 :apidocs_link: https://www.keycloak.org/docs/{project_version}/api_documentation/
 :bootstrapadminrecovery_name: Admin Bootstrap and Recovery
 :bootstrapadminrecovery_link: https://www.keycloak.org/server/bootstrap-admin-recovery
+:client_certificate_lookup_link: https://www.keycloak.org/server/reverseproxy#_enabling_client_certificate_lookup
 :developerguide_name: Server Developer Guide
 :developerguide_name_short: Server Developer
 :developerguide_link: {project_doc_base_url}/server_development/

diff --git a/docs/guides/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc
@@ -159,6 +159,23 @@ For example:
 When the proxy is configured as a TLS termination proxy the client certificate information can be forwarded to the server through specific HTTP request headers and then used to authenticate
 clients. You are able to configure how the server is going to retrieve client certificate information depending on the proxy you are using.
 
+[WARNING]
+====
+Client certificate lookup via a proxy header for X.509 authentication is considered security-sensitive. If misconfigured, a forged client certificate header can be used for authentication.
+*Extra precautions need to be taken to ensure that the client certificate information can be trusted when passed via a proxy header.*
+
+* Double check your use case needs reencrypt or edge TLS termination which implies using a proxy header for client certificate lookup. TLS passthrough is recommended as a more secure option
+  when X.509 authentication is desired as it does not require passing the certificate via a proxy header. Client certificate lookup from a proxy header is applicable only to reencrypt
+  and edge TLS termination.
+* If passthrough is not an option, implement the following security measures:
+** Configure your network so that {project_name} is isolated and can accept connections only from the proxy.
+** Make sure that the proxy overwrites the header that is configured in `spi-x509cert-lookup-<provider>-ssl-client-cert` option.
+** Keep in mind that any of the `spi-x509cert-*` options don't reflect the `proxy-trusted-addresses` option.
+** Pay extra attention to the `spi-x509cert-lookup-<provider>-trust-proxy-verification` setting. Make sure you enable it only if you can trust your proxy to verify the client certificate.
+   Setting `spi-x509cert-lookup-<provider>-trust-proxy-verification=true` without the proxy verifying the client certificate chain will expose {project_name} to security vulnerability
+   when a forged client certificate can be used for authentication.
+====
+
 The server supports some of the most commons TLS termination proxies such as:
 
 [%autowidth]