mirror/keycloak
1
0
Fork 0
mirror of https://github.com/keycloak/keycloak.git synced 2025-12-21 14:30:05 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update docs with security warning around client certificate lookup (#215)

Browse Source 
Closes #203

Signed-off-by: Václav Muzikář <vmuzikar@redhat.com>
This commit is contained in:
Václav Muzikář
2024-11-13 16:18:26 +01:00
committed by GitHub
parent b01a55710d
commit 3da16eed1f
4 changed files with 27 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/documentation/topics/templates/document-attributes.adoc
View File

@@ -61,6 +61,7 @@
:adminguide_clearcache_link: {adminguide_link}#_clear-cache
:apidocs_name: API Documentation
:apidocs_link: https://www.keycloak.org/docs/{project_version}/api_documentation/
: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/

6
docs/documentation/upgrading/topics/changes/changes-24_0_9.adoc Normal file
View File

@@ -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.

4
docs/documentation/upgrading/topics/changes/changes.adoc
View File

@@ -1,6 +1,10 @@
[[migration-changes]]
== Migration Changes
=== Migrating to 24.0.9
include::changes-24_0_9.adoc[leveloffset=3]
=== Migrating to 24.0.7
include::changes-24_0_7.adoc[leveloffset=3]

16
docs/guides/server/reverseproxy.adoc
View File

@@ -178,6 +178,22 @@ If not, prefix the path with your desired one.
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.
** 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]