Skip to content

Keycloak Installation and Configuration Tutorial

1. Install Java and Required Packages

Install OpenJDK, Apache Certbot, and other utilities:

apt install openjdk-21-jdk-headless unzip python3-certbot-apache vim

2. Obtain an SSL Certificate

Use Certbot to generate an SSL certificate for your server’s fully qualified domain name (FQDN):

certbot --apache -d server-fqdn

3. Download and Prepare Keycloak

Navigate to /opt, download Keycloak, and extract it:

cd /opt
wget https://github.com/keycloak/keycloak/releases/download/26.0.5/keycloak-26.0.5.zip
unzip keycloak-26.0.5.zip
mv keycloak-26.0.5/ keycloak
cd keycloak/

4. Configure Keycloak Settings

Edit the Keycloak configuration file to set the hostname:

vim /opt/keycloak/conf/keycloak.conf

Add your server’s hostname:

hostname=server-fqdn

Set the SSL certificate paths:

https-certificate-key-file=/etc/letsencrypt/live/server-fqdn/privkey.pem
https-certificate-file=/etc/letsencrypt/live/server-fqdn/fullchain.pem

Copy ca_certs.pem from your LDAP configuration into Keycloak’s truststore directory:

cp /path/to/ca_certs.pem /opt/keycloak/conf/truststores/

5. Start Keycloak in Development Mode

Start Keycloak with the following command:

KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin ./bin/kc.sh start-dev

You can now access the Keycloak Admin Console at:

https://server-fqdn:8443/admin

6. Create a Permanent Admin Account

  1. In the Admin Console, navigate to Users → Add User.
  2. Under Credentials, set a permanent password by disabling the “Temporary” button.
  3. Go to Role Mapping → Assign Role → filter by realm roles.
  4. Select Admin and click Assign.

7. Create and Customize a New Realm

From the Master drop-down menu, select Create Realm. - Name your realm (e.g., YOUR-DOMAIN) and click Add.

Customize Realm Settings

General Settings:

  1. Go to Realm Settings → General tab.

  2. Set Display Name as Your Institute.

  3. Enter HTML Display Name as <span><img src="URL-TO-YOUR-LOGO"></span>.

  4. Set Require SSL to “All requests.”

Login Settings:

  1. Go to the Login tab.

  2. Enable Forgot password.

  3. Disable Login with email.

8. Connect to LDAP

  1. Go to User Federation → select LDAP from the add provider drop-down.

  2. Configure LDAP settings as follows:

  3. UI Display Name: [e.g., My LDAP]

  4. Vendor: Other
  5. Connection URL: ldap://ldap-server-fqdn
  6. Enable StartTLS: On
  7. Use Truststore SPI: Always
  8. Bind Type: Simple
  9. Bind DN: cn=admin,dc=your-domain,dc=edu,dc=gh
  10. Bind Credentials: [LDAP admin password]

LDAP Searching and Updating:

  • Edit Mode: WRITEABLE
  • Users DN: ou=people,dc=your-domain,dc=edu,dc=gh
  • Username LDAP Attribute: uid
  • RDN LDAP Attribute: uid
  • UUID LDAP Attribute: uid
  • User Object Classes: inetOrgPerson, organizationalPerson, eduPerson, extensibleObject
  • Search Scope: Subtree

Synchronization Settings:

  • Enable Import Users, Sync Registrations, Periodic Full Sync, and Periodic Changed users sync.

Advanced settings:

  • Enable Validate password policy and Trust Email

9. Map User Attributes

For password resets, map attributes such as email:

  1. Go to User Federation → LDAP → Mappers.
  2. Select email mapper and set LDAP Attribute to email.
  3. Similarly, map first name with givenName.

10. Configure Email Server (Optional for Production)

Set up email server settings under Realm Settings → Email for notifications.

11. Set Up User Profile and OTP

Users can log in to their profile to update details and use OTP for additional security.

12. Define Password Policy

Go to Authentication → Password Policy to enforce requirements like password complexity and expiration.