When it comes to securing Keycloak, an open-source identity and access management solution, using HTTPS is a crucial step in protecting user credentials and other sensitive data. In this article, we’ll explore the benefits of using HTTPS with Keycloak and provide a step-by-step guide on how to enable HTTPS in your Keycloak installation.
Firstly, if you are new to Keycloak powered by Quarkus, we recommend having a look at the following article: Getting started with Keycloak powered by Quarkus
By using HTTPS, you can ensure that all communication between your Keycloak server and clients is encrypted and secure. This is especially important if you’re using Keycloak to manage user authentication and authorization for your web application, as it prevents attackers from stealing user credentials and gaining unauthorized access to your application.
Enabling HTTPS in Keycloak is a straightforward process. Here’s a step-by-step guide on how to do it:
Create or obtain an SSL/TLS certificate
Before you can enable HTTPS in Keycloak, you’ll need to obtain an SSL/TLS certificate from a trusted certificate authority (CA). You can purchase a certificate from a commercial CA, request a free certificate from Let’s Encrypt or use a self-signed certificate.
For learning purposes we will create a self-signed certificate. You can either use a Java KeyStore for this purpose or a Pem File.
Using a Java Keystore to secure Keycloak
The Java keystore (JKS) is a proprietary format used by Java-based applications. The JKS file is password-protected, meaning that you need to provide a password to access and manipulate the keys and certificates within the keystore.
keytool -genkeypair -alias localhost -keyalg RSA -keysize 2048 -validity 365 -keystore server.keystore -dname "cn=Server Administrator,o=Acme,c=GB" -keypass secret -storepass secret
Next, rebuild your Keycloak configuration:
Then, if you copy the above server.keystore into the conf folder of your installation, Keycloak will assume that you want to use that file, when you explicitly disable the default (http) protocol with http-enabled set to false.
/kc.sh start --http-enabled=false --https-key-store-password=secret --hostname=fedora
On the other hand, if you want to provide the Keystore in a custom location, then use the https-key-store-file property. For example:
./kc.sh start --https-key-store-file=/path/server.keystore --https-key-store-password=secret --hostname=fedora
Securing Sensitive information in a Vault
The previous Keycloak WildFly distribution provided a built-in vault provider to use secrets from a keystore-backed Elytron credential store. The new Keycloak Quarkus distribution deprecates this mechanism and will add a Quarkus based solution to manage the vault. The following discussion captures the status of this change: https://github.com/keycloak/keycloak/discussions/19281
Securing Keycloak with a Pem File and certificate
PEM is a widely-used text-based format that originated from the Privacy-Enhanced Mail standard. It is not specific to Java and can be used across different platforms and programming languages. A PEM file typically contains a single certificate or a private key. However, it can also include multiple certificates, such as a certificate chain.
If you want to create a self-signed key file and certificate for testing purposes, you can follow these steps:
Generate a private key: Use OpenSSL to generate a private key in PEM format. Run the following command:
openssl genrsa -out keycloak.key 2048
This command will generate a 2048-bit RSA private key and save it in the keycloak.key file.
Generate a self-signed certificate: Use the private key to generate a self-signed certificate. Run the following command:
openssl req -new -x509 -sha256 -key keycloak.key -out keycloak.crt -days 365
This command will prompt you to enter some information for the certificate. You can provide the required information or leave it blank for testing purposes. The self-signed certificate will be saved in the keycloak.crt file.
Create the PEM key file: To create the PEM key file, rename the private key file to have the .pem extension:
mv keycloak.key keycloak.pem
Create the PEM certificate file: To create the PEM certificate file, concatenate the self-signed certificate with the private key file. Run the following command:
cat keycloak.crt >> keycloak.pem
Now you have the PEM key file (keycloak.pem) and the PEM certificate file (keycloak.pem) generated as a self-signed set for testing purposes.
You can start Keycloak using PEM files as follows:
./kc.sh start --https-certificate-file=/path/keycloak.crt --https-certificate-key-file=/path/keycloak.pem --hostname=fedora
Testing secured Keycloak
You can verify that your Keycloak distribution uses HTTPS by checking the default server address and port. For example: https://localhost:8443
Two-way Secure communication
To enable the validation of client certificates and support authentication methods like two-way TLS, it is necessary to establish a trust store containing all the trusted certificates (including the certificate chain) that the server should recognize. Various capabilities, such as Mutual-TLS Client Authentication and End-User X.509 Browser Authentication, rely on this trust store for proper client certificate authentication. To configure the location of this trust store, execute the following command:
./kc.sh start --https-trust-store-file=/path/truststore --https-trust-store-password=password
Finally, if you want to control the validation Client certificates that are accessing Keycloak you can set the property https-client-auth as follows:
none: Keycloak will not request or validate Client certificates
required: Keycloak will always request Client valid certificates
request: Keycloak will also accept requests without a certificate and only validate the a certificate if it exists
In conclusion, implementing HTTPS security measures for Keycloak is not just a recommendation, but a crucial step towards ensuring the utmost protection for user data and authentication processes. By securing Keycloak with SSL/HTTPS, organizations can establish encrypted connections, prevent data interception and tampering, and enhance overall system security.