Chapter 13. Configuring trusted certificates for mTLS In order to properly validate client certificates and enable certain authentication methods like two-way TLS or mTLS, you can set a trust store with all the certificates (and certificate chain) the server should be trusting. There are number of capabilities that rely on this trust store to properly authenticate clients using certificates such as Mutual TLS and X.509 Authentication. 13.1. Enabling mTLS Authentication using mTLS is disabled by default. To enable mTLS certificate handling when Red Hat build of Keycloak is the server and needs to validate certificates from requests made to Red Hat build of Keycloak endpoints, put the appropriate certificates in a truststore and use the following command to enable mTLS: bin/kc.[sh|bat] start --https-client-auth=<none|request|required> Using the value required sets up Red Hat build of Keycloak to always ask for certificates and fail if no certificate is provided in a request. By setting the value to request , Red Hat build of Keycloak will also accept requests without a certificate and only validate the correctness of a certificate if it exists. Warning The mTLS configuration and the truststore is shared by all Realms. It is not possible to configure different truststores for different Realms. Note Management interface properties are inherited from the main HTTP server, including mTLS settings. It means when mTLS is set, it is also enabled for the management interface. To override the behavior, use the https-management-client-auth property. 13.2. Using a dedicated truststore for mTLS By default, Red Hat build of Keycloak uses the System Truststore to validate certificates. See Configuring trusted certificates for details. If you need to use a dedicated truststore for mTLS, you can configure the location of this truststore by running the following command: bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file --https-trust-store-password=<value> 13.3. Additional resources 13.3.1. Using mTLS for outgoing HTTP requests Be aware that this is the basic certificate configuration for mTLS use cases where Red Hat build of Keycloak acts as server. When Red Hat build of Keycloak acts as client instead, e.g. when Red Hat build of Keycloak tries to get a token from a token endpoint of a brokered identity provider that is secured by mTLS, you need to set up the HttpClient to provide the right certificates in the keystore for the outgoing request. To configure mTLS in these scenarios, see Configuring outgoing HTTP requests . 13.3.2. Configuring X.509 Authentication For more information on how to configure X.509 Authentication, see X.509 Client Certificate User Authentication section . 13.4. Relevant options Value https-client-auth 🛠 Configures the server to require/request client authentication. CLI: --https-client-auth Env: KC_HTTPS_CLIENT_AUTH none (default), request , required https-trust-store-file The trust store which holds the certificate information of the certificates to trust. CLI: --https-trust-store-file Env: KC_HTTPS_TRUST_STORE_FILE https-trust-store-password The password of the trust store file. CLI: --https-trust-store-password Env: KC_HTTPS_TRUST_STORE_PASSWORD https-trust-store-type The type of the trust store file. If not given, the type is automatically detected based on the file extension. If fips-mode is set to strict and no value is set, it defaults to BCFKS . CLI: --https-trust-store-type Env: KC_HTTPS_TRUST_STORE_TYPE https-management-client-auth 🛠 Configures the management interface to require/request client authentication. If not given, the value is inherited from HTTP options. Relevant only when something is exposed on the management interface - see the guide for details. CLI: --https-management-client-auth Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH none (default), request , required

Commands:
bin/kc.[sh|bat] start --https-client-auth=<none|request|required>
bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file --https-trust-store-password=<value>