libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

Updating proxy guide with x509 client certificate lookup (#10220)

Browse source 
Closes #10222
This commit is contained in:
Pedro Igor 2022-02-16 11:47:04 -03:00 committed by GitHub
parent 68ada40197
commit f750c2e0f7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 48 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
docs/guides/src/main/server/reverseproxy.adoc
View file

@ -92,4 +92,52 @@ The following table shows the recommended paths to expose.
We assume you run Keycloak on the root path `/` on your reverse proxy/gateway's public API.
If not, prefix the path with your desired one.
=== Enabling client certificate lookup
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.
The server supports some of the most commons TLS termination proxies such as:
|===
|Proxy|Provider
|Apache HTTP Server
|apache
|HAProxy
|haproxy
|NGINX
|nginx
|===
To configure how client certificates are retrieved from the requests you need to:
.Enable the corresponding proxy provider
<@kc.build parameters="--spi-x509cert-lookup-provider=<provider>"/>
.Configure the HTTP headers
<@kc.start parameters="--spi-x509cert-lookup-<provider>-ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup-<provider>-ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup-<provider>-certificate-chain-length=10"/>
When configuring the HTTP headers, you need to make sure the values you are using correspond to the name of the headers
forwarded by the proxy with the client certificate information.
The available options for configuring a provider are:
|===
|Option|Description
|ssl-client-cert
| The name of the header holding the client certificate
|ssl-cert-chain-prefix
| The prefix of the headers holding additional certificates in the chain and used to retrieve individual
certificates accordingly to the length of the chain. For instance, a value `CERT_CHAIN` will tell the server
to load additional certificates from headers `CERT_CHAIN_0` to `CERT_CHAIN_9` if `certificate-chain-length` is set to `10`.
|certificate-chain-length
| The maximum length of the certificate chain.
|===
</@tmpl.guide>