Installing Keycloak on Centos
Keycloak is an application that offers open source identity and access management for modern applications and services. This article will take you through the process of installing Keycloak on a Centos 8 server.
For the original documentation on installing Keycloak visit https://www.keycloak.org/getting-started which details the installation of Keycloak on various platforms. This guide will focus on installing a standalone Keycloak 11.0.1 server running on Centos 8 connecting to a PostgreSQL 12 server running externally. The setup of the PostgreSQL server is out of the scope of this document however you will need the jdbc connection url as well as the username and password to establish the connection.
# Prepatory work yum update yum install java-1.8.0-openjdk-devel yum install wget yum install zip # Add user and group to run keycloak groupadd -r keycloak useradd -m -d /var/lib/keycloak -s /sbin/nologin -r -g keycloak keycloak # Create the base directory for the keycloak installation mkdir -p /opt/keycloak # Download the keycloak zip file wget https://downloads.jboss.org/keycloak/11.0.1/keycloak-11.0.1.zip -P /opt/keycloak unzip keycloak-11.0.1.zip -d /opt/keycloak # Create a symbolic link to the Keycloak installation to allow for easy switching of versions should need arise ln -s /opt/keycloak/keycloak-11.0.1 /opt/keycloak/current # Assign permissions to keycloak folder to the user and group we created chown keycloak: -R /opt/keycloak # Lock down the standalone directory so only the keycloak user has access to it chmod 700 /opt/keycloak/current/standalone # Create a systemd configuration to start and stop keycloak using systemd cat > /etc/systemd/system/keycloak.service <<EOF [Unit] Description=Keycloak After=network.target [Service] Type=idle User=keycloak Group=keycloak ExecStart=/opt/keycloak/current/bin/standalone.sh -b 0.0.0.0 TimeoutStartSec=600 TimeoutStopSec=600 [Install] WantedBy=multi-user.target EOF systemctl daemon-reload systemctl enable keycloak systemctl start keycloak # KEYCLOAK INSTALLATION COMPLETE
Installing PostgreSQL Driver (Optional)
By default the Keycloak installation utilises an embedded H2 database. In order to use PostgreSQL perform the following
# Download PostgreSQL database drivers mkdir -p /opt/drivers/jdbc wget https://jdbc.postgresql.org/download/postgresql-42.2.16.jar -P /opt/drivers/jdbc
# Add the PostgreSQL module in the Wildfly installation (can be run offline) module add --name=org.postgresql --dependencies=javax.api,javax.transaction.api --resources="/opt/drivers/jdbc/postgresql-42.2.16.jar" # Add the PostgreSQL driver to the configuration /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql,driver-class-name=org.postgresql.Driver) # Remove the current Keycloak H2 datasource /subsystem=datasources/data-source=KeycloakDS:remove # Update the KeycloakDS datasource to use the PostgreSQL. Ensure you have set the database up before hand. /subsystem=datasources/data-source=KeycloakDS:add(driver-name=postgresql,enabled=true,use-java-context=true,connection-url="jdbc:postgresql://host:port/database",jndi-name="java:/jboss/datasources/KeycloakDS",user-name=keycloak,password="PASSWORD",max-pool-size=20)
Enabling SSL (Optional)
In order to allow HTTPS connections, you need to obtain a self signed or third-party signed certificate and import it into a Java keystore before you can enable HTTPS in the web container you are deploying the Keycloak Server to. There are many possible configurations here consider. Here we will consider a setup using a self signed certificate. the references given at the end to
# Generate the self signed certificate keytool -genkeypair -alias localhost -keyalg RSA -keysize 2048 -validity 1095 -keystore keytool -genkeypair -alias localhost -keyalg RSA -keysize 2048 -validity 1095 -keystore /opt/keycloak/current/standalone/configuration/application.keystore -dname "cn=XXXXXXX,o=XXXXXX,c=XX" -keypass PRIVATE-KEY-PASSWORD -storepass KEYSTORE-PASSWORD
Ensure that Keycloak is up and running before running the following on a connected JBoss CLI console.
# You will need to have the SSL certificate available before hand. See https://www.keycloak.org/docs/latest/server_installation/#_setting_up_ssl for details of how to generate the certificate # Configure Wildfly keystore /core-service=management/security-realm=ApplicationRealm/server-identity=ssl/:write-attribute(name=keystore-path,value=application.keystore) /core-service=management/security-realm=ApplicationRealm/server-identity=ssl/:write-attribute(name=keystore-password,value=KEYSTORE-PASSWORD) /core-service=management/security-realm=ApplicationRealm/server-identity=ssl/:write-attribute(name=key-password,value=PRIVATE-KEY-PASSWORD) /core-service=management/security-realm=ApplicationRealm/server-identity=ssl/:write-attribute(name=alias,value=ALIAS) # Configure Keycloak to use keystore /core-service=management/security-realm=UndertowRealm:add() /core-service=management/security-realm=UndertowRealm/server-identity=ssl:add(keystore-path=keycloak.jks, keystore-relative-to=jboss.server.config.dir, keystore-password=PoliteAsk)
Access the Web Console
Once the installation is complete by default you can access Keycloak on the default http://localhost:8080/auth url. You can create the admin user on this console as long as you access it through localhost. If you do not have access to the localhost you can create the admin user by running the following command
/opt/keycloak/current/bin/add-user-keycloak.sh -r master -u admin -p PASSWORD
Odds and Ends
There are features in Keycloak that are not enabled by default, these include features that are not fully supported. In addition there are some features that are enabled by default, but that can be disabled. Refer to the official documentation to understand what these are and how to enable should you wish to.
