What Is Keycloak?

Keycloak is an open-source identity and access management solution that provides robust authentication and authorization services for web and mobile applications. Developed by Red Hat, Keycloak simplifies the implementation of security features by offering a centralized and customizable authentication server. It supports various authentication protocols, including OpenID Connect, OAuth 2.0, and SAML, allowing developers to integrate single sign-on (SSO) capabilities seamlessly. Keycloak's versatile features include user federation, role-based access control, and social identity provider integration, enabling organizations to secure their applications with ease. Its user-friendly administration console facilitates the management of users, groups, and client applications, making it a popular choice for enterprises seeking a comprehensive identity management solution.

Prerequisites

For following along with this tutorial-like blog post you need to have these things before diving in with us.

• Codesphere Account
• PostgreSQL Database (can be purchased from Codesphere)

Getting a database from Codesphere.

• Go to https://codesphere.com/ide/menu/services
• In the databases section, click on the "Create" button.
• Select PostgreSQL from the dropdown of the available databases.
• Click on the "Create" button once you have chosen your preferred plan (the minimum plan required is Free but the Micro plan is recommended).
• Wait for the "Actions" tab to show the text, "Show info". This may take a while.
• Click on the "Show info" button and copy the "Connection String". This is the database URL you will need in the further steps.

Installing Keycloak On Codesphere.

• Navigate to Codesphere's workspaces page.
• Click on the "New Workspace" button.
• Create a new workspace with the GitHub URL: https://github.com/codesphere-community/Keycloak
• Click on the "Create" button after choosing your preferred settings.
• Head over to the "Setup" section of the IDE.
• Click on "Env vars" in the list.
• Click on the "Add new variable" option to add a variable.
• Add the variables:
  • DATABASE_URL (The PostgreSQL database URL).
  • KEYCLOAK_ADMIN (The admin username).
  • KEYCLOAK_ADMIN_PASSWORD (The admin password).
• Click on the "CI Pipeline" button at the bottom of the page.
• Click on the "Run" button to run the installation script. Go to the next step only after the "Prepare" button on the left panel turn Green in colour.
• Click on the "Run" button on the left panel.
• Click on the smaller "Run" button on the right panel.
• If this is the first time installation, wait for about 1 minute before continuing to the next step this is because it's running the build script and then starting the server. After the first time, it would start in under 15 seconds.
• Click on the "Open Deployment" button on the top panel of the page.
• After Keycloak opens, click on the "Administration Console" button.
• Log in with your environment variables KEYCLOAK_ADMIN (username) and KEYCLOAK_ADMIN_PASSWORD (password) Congratulations, You have successfully set up Keycloak on Codesphere 🎉

Updating

Go to the "CI Pipelines" and then run the "Prepare" CI command. This will automatically delete the old version and update it to the latest version. Stop (if needed) and then Re-Run the "Run" CI command to restart it.

Customizing settings in the start command.

In this tutorial, we will explore how we can change the starting parameters in Codesphere CI Commands.
For this tutorial, we will change the maximum queued requests per second in Keycloak. This tutorial can even be used in case you want to change any type of configuration.

Maximum queued requests per second or http-max-queued-requests in Keycloak sets the limit for queued HTTP requests. It prevents server overload by rejecting requests beyond the specified limit, maintaining stability during high traffic. Adjusting this parameter optimizes server performance under varying loads.

• Open the "Setup" section.
• Click on the "CI" section.
• Click on the "Stage 3: Run" button and then click the "Edit" button.
• Scroll to the end of the command then append your command. In this case, we want to put --http-max-queued-requests with the value of 100.
• Click on the "Submit" button.
• Click on the "CI Pipeline" button at the bottom of the page.
• Go to the "Run" section of the CI Pipeline and click on the red "Stop" button in case the server is running.
• Now click the blue-violet "Run" button to run to again start the server. This will now run with the changes we made.

Now, any changes made in the start command will be reflected instantly (custom commands can take time to start the first time in case there are any major change made)!

More customization

You can find more customization options here: https://www.keycloak.org/server/all-config Follow the same steps as mentioned above to edit the start command and see your changes!

Explanation of the install.sh file:

#!/bin/bash

# List of the required environment variables.
required_vars=("KEYCLOAK_ADMIN" "KEYCLOAK_ADMIN_PASSWORD" "DATABASE_URL")
missing_vars=()

# Check if an old version of Keycloak is present.
# If it is present, delete the older version.
# This is to ensure the latest updates & security patches.
if [ -f ./KEYCLOAK_VERSION ]; then
	echo [LOG] Removing Previous Version Of Keycloak!
	rm -rf keycloak-$(cat ./KEYCLOAK_VERSION)
fi

# Check whether the required environment variables are present.
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        missing_vars+=("$var")
    fi
done

# Display a message in case there is an environment variable missing.
if [ ${#missing_vars[@]} -gt 0 ]; then
    echo "Please set the following environment variables before installation: ${missing_vars[*]}"
    exit 1
fi

# Set the required variables to proceed with the installation.
repo_url="https://github.com/keycloak/keycloak"
version_file="KEYCLOAK_VERSION"

# Fetch the latest version of Keycloak to include the latest updates & security patches.
latest_tag=$(curl -sSLI -o /dev/null -w '%{url_effective}' "${repo_url}/releases/latest" | awk -F/ '/tag/{print $NF}')

# Just in case the script is unable to fetch the latest version.
if [ -z "$latest_tag" ]; then
    echo "Failed to retrieve the latest release tag. Exiting."
    exit 1
fi

# Write the latest version to a separate file so that it can be started & updated in the future.
echo "$latest_tag" > "$version_file"
download_url="${repo_url}/releases/download/${latest_tag}/keycloak-${latest_tag}.tar.gz"
destination_file="keycloak-${latest_tag}.tar.gz"

# Download the Keycloak code.
echo "[LOG] Downloading Latest Version Of Keycloak: ${download_url}..."
curl -sSL -o "${destination_file}" "${download_url}" && echo "Download successful! File saved as ${destination_file}" || echo "Download failed. Please try again."

# Keycloak requires Java, the below script installs Java from NixPkgs for NixOS (https://search.nixos.org/packages?channel=23.11&show=zulu&from=0&size=50&sort=relevance&type=packages&query=java)
echo "[LOG] Installing Java via Zulu"
nix-env -iA nixpkgs.zulu

# Extract the compressed file.
echo "[LOG] Extracting Keycloak"
tar -xvf ./keycloak-${latest_tag}.tar.gz

# Delete the compressed file since it has already been uncompressed.
echo "[LOG] Deleting the tar file"
rm -rf ./keycloak-${latest_tag}.tar.gz

# Configure the database
echo "[LOG] Configuring the database"
chmod +x ./config.sh
./config.sh

# Complete Confirmation!
echo "[LOG] Installation Completed. Execute the \"RUN\" CI command."

Explanation of the config.sh file:

#!/bin/bash

# Get the database url from the environment variable
url=$DATABASE_URL

# Remove the not required content
url=$(echo "$url" | sed 's/?sslmode=require//')

# Extracting components from the database URL
# This is done because Keycloak isn't allowing using the full database URL directly
username=$(echo "$url" | awk -F '://' '{split($2,a,"@"); print a[1]}' | awk -F ':' '{print $1}')
password=$(echo "$url" | awk -F '://' '{split($2,a,"@"); print a[1]}' | awk -F ':' '{print $2}')
host=$(echo "$url" | awk -F '://' '{split($2,a,"@"); print a[2]}' | awk -F '?' '{print $1}')
host_port_path=$(echo "$url" | awk -F '://' '{split($2,a,"@"); print a[2]}' | awk -F '?' '{print $1}')
IFS='/' read -r host_port path <<< "$host_port_path"
IFS=':' read -r host port <<< "$host_port"

# Constructing the JDBC URL
db_url="jdbc:postgresql://$host:$port/$path"

# Remove the previous configuration
rm -rf ./keycloak-$(cat ./KEYCLOAK_VERSION)/conf/keycloak.conf

# Writing a new, updated configuration
echo "db=postgres" > ./keycloak-$(cat ./KEYCLOAK_VERSION)/conf/keycloak.conf
echo "db-username=$username" >> ./keycloak-$(cat ./KEYCLOAK_VERSION)/conf/keycloak.conf
echo "db-password=$password" >> ./keycloak-$(cat ./KEYCLOAK_VERSION)/conf/keycloak.conf
echo "db-url=$db_url" >> ./keycloak-$(cat ./KEYCLOAK_VERSION)/conf/keycloak.conf