Posted on

Setting Up Keycloak as a Systemd Service

Running Keycloak as a systemd service allows you to manage its lifecycle effectively, ensuring that it starts automatically on boot and can be easily started, stopped, or restarted using systemd commands. This guide will show you how to configure Keycloak as a systemd service for both traditional and Docker-based deployments.

1. Prerequisites

Before configuring Keycloak as a systemd service, make sure you have the following:

  • A working Keycloak installation (either standalone or Docker-based).
  • Systemd installed and running on your server (most modern Linux distributions include systemd by default).
  • Root or sudo privileges to manage systemd services.

2. Setting Up Keycloak as a Systemd Service (Traditional Installation)

If you have a standalone Keycloak installation (non-Docker), follow these steps to configure Keycloak as a systemd service:

  1. Navigate to the Keycloak installation directory, where the Keycloak executable resides (e.g., /opt/keycloak).
  2. Create a new systemd service file for Keycloak:
  3. Paste the following configuration into the service file:
  4. Save and close the file (Ctrl + X, Y, Enter).
  5. Reload the systemd configuration to apply the new service:
  6. Enable the Keycloak service to start automatically at boot:
  7. Start the Keycloak service:
  8. Check the status of the Keycloak service to ensure it is running:
sudo nano /etc/systemd/system/keycloak.service

[Unit]
Description=Keycloak
After=network.target

[Service]
User=root
Group=root
ExecStart=/opt/keycloak/bin/standalone.sh -b 0.0.0.0
or
ExecStart=/opt/keycloak/bin/kc.sh start

ExecStop=/opt/keycloak/bin/jboss-cli.sh --connect command=:shutdown
or 

ExecStop=/opt/keycloak/bin/kc.sh stop

Restart=always
LimitNOFILE=1024

[Install]
WantedBy=multi-user.target

This configuration does the following:

  • ExecStart: Specifies the command to start Keycloak.
  • ExecStop: Specifies the command to stop Keycloak.
  • Restart: Ensures Keycloak restarts automatically if it crashes.
  • LimitNOFILE: Increases the number of open files allowed for Keycloak (useful for production environments).
sudo systemctl daemon-reload
sudo systemctl enable keycloak.service
sudo systemctl start keycloak.service
sudo systemctl status keycloak.service

3. Setting Up Keycloak as a Docker-based Systemd Service

If you’re running Keycloak in Docker, you can still manage it using systemd. Here’s how to set up a systemd service for Docker-based Keycloak:

  1. Create a new systemd service file for Docker-based Keycloak:
  2. Paste the following configuration into the service file:
  3. Save and close the file (Ctrl + X, Y, Enter).
  4. Reload the systemd configuration to apply the new service:
  5. Enable the Docker-based Keycloak service to start automatically at boot:
  6. Start the Keycloak Docker service:
  7. Check the status of the Docker-based Keycloak service:
sudo nano /etc/systemd/system/keycloak-docker.service

[Unit]
Description=Keycloak Docker Container
After=docker.service
Requires=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker run --rm --name keycloak -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin jboss/keycloak
ExecStop=/usr/bin/docker stop keycloak

[Insta
Posted on

How to Fix “Key material not provided to setup HTTPS” Error in Keycloak

When setting up Keycloak with HTTPS, you might encounter the error: “Key material not provided to setup HTTPS. Please configure your keys/certificates or start the server in development mode.” This message typically indicates that Keycloak cannot find the necessary SSL certificates or keys to enable HTTPS. In this article, we’ll guide you through the steps to resolve this issue by properly configuring your SSL certificates or by starting the server in development mode for testing purposes.

1. Understanding the Error

Keycloak requires SSL certificates and key files to establish secure HTTPS connections. When these files are missing or misconfigured, Keycloak cannot start the HTTPS listener and throws the error mentioned above. This issue can occur if:

  • The certificate files (key material) are not provided.
  • The Keycloak server is not properly configured to use SSL certificates.
  • You are running Keycloak in a non-production environment where SSL certificates are not required.

2. Fixing the Issue: Configure SSL Certificates

To resolve this error, you need to provide the SSL certificates (key material) required by Keycloak. Follow these steps to configure HTTPS in Keycloak properly:

  1. Obtain or create an SSL certificate for your domain. If you’re testing locally or don’t want to use a certificate from a trusted CA (Certificate Authority), you can generate a self-signed certificate using OpenSSL. Here’s a command to generate a self-signed certificate:
  2. openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout keycloak.key -out keycloak.crt
  3. Move the generated certificate and key files to the appropriate directory on your server (e.g., /opt/keycloak/ssl or another directory of your choice).
  4. Edit the keycloak.conf configuration file to point to your SSL certificate and key files. Add the following lines:
  5. https.key-store-file=/opt/keycloak/ssl/keycloak.p12
  6. https.key-store-password=yourpassword
  7. https.key-store-provider=PKCS12
  8. If you’re using a self-signed certificate, make sure to disable SSL verification on clients or configure your clients to trust the certificate.
  9. Restart Keycloak to apply the changes:
  10. sudo systemctl restart keycloak

3. Option: Run Keycloak in Development Mode (for Testing Purposes)

If you don’t need to configure HTTPS in a development or test environment, you can bypass the SSL certificate configuration by starting Keycloak in development mode. This will disable HTTPS and allow you to access Keycloak over HTTP.

  1. Navigate to the Keycloak directory:
  2. cd /opt/keycloak
  3. Start Keycloak in development mode by setting the keycloak.profile environment variable to dev:
  4. ./bin/standalone.sh -Dkeycloak.profile=dev
  5. Alternatively, if you’re using Docker, you can start Keycloak in development mode with the following command:
  6. docker run -e KEYCLOAK_PROFILE=dev jboss/keycloak
  7. This will start Keycloak without requiring SSL certificates and will allow you to test it over HTTP.

4. Troubleshooting

If you continue to encounter issues after configuring the certificates or running in development mode, consider the following:

  • Double-check the file paths to ensure Keycloak is correctly pointing to the SSL certificate and key files.
  • Ensure that your firewall or security settings are not blocking the HTTPS port (usually port 443).
  • Look at the Keycloak logs for any additional error messages related to SSL configuration:
  • sudo tail -f /opt/keycloak/standalone/log/server.log
  • If you’re using a self-signed certificate, make sure your clients are configured to trust it, or disable SSL verification for testing purposes.

5. Conclusion

The “Key material not provided to setup HTTPS” error in Keycloak typically occurs when the server is not configured with the necessary SSL certificates or keys. By either providing the required certificates or running Keycloak in development mode, you can resolve this issue. For production environments, always ensure you use valid SSL certificates to secure your Keycloak server. For development and testing, running Keycloak in development mode can help bypass the need for SSL certificates temporarily.