--- title: "How to Install Keycloak for SSO on Ubuntu 24.04" description: "Deploy Keycloak with PostgreSQL in Docker on Ubuntu 24.04 behind Nginx with HTTPS, then create a realm, an OIDC client and a user for single sign-on." category: "Identity and Access Management" language: en source: https://cubepath.com/docs/identity-and-access-management/keycloak-installation-for-sso updated: 2026-09-25 --- # How to Install Keycloak for SSO on Ubuntu 24.04 Keycloak is an open source identity and access management server. It gives your applications single sign-on through OpenID Connect (OIDC) and SAML 2.0, and can federate users from LDAP or Active Directory. In this tutorial you will run Keycloak and PostgreSQL with Docker Compose on Ubuntu 24.04, publish it at `https://auth.example.com` through Nginx with a Let's Encrypt certificate, and create a realm, an OIDC client and a user that an application can sign in with. ## Prerequisites To follow this guide you need: - A server running Ubuntu 24.04 LTS with at least 2 vCPUs and 2 GB of RAM (4 GB for production), for example a CubePath VPS. - A non-root user with `sudo` privileges. - A domain name with a DNS A record, such as `auth.example.com`, pointing to the server's public IP. Replace `auth.example.com` with your own hostname throughout the guide. - Ports 80 and 443 open to the internet. ## Step 1 - Installing Docker and Nginx Ubuntu 24.04 packages Docker Engine and the Compose v2 plugin, which is enough for this setup. Install them together with Nginx and Certbot: ```bash sudo apt update sudo apt install docker.io docker-compose-v2 nginx certbot python3-certbot-nginx ``` Allow web traffic through UFW. If UFW is not enabled yet, allow SSH first so you keep access: ```bash sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw enable ``` Check that Docker and Compose work: ```bash sudo docker compose version ``` ```output Docker Compose version 2.24.6+ds1-0ubuntu2 ``` ## Step 2 - Writing the Docker Compose file Create a directory for the deployment: ```bash sudo mkdir -p /opt/keycloak cd /opt/keycloak ``` Keep the database password out of the Compose file by storing it in an `.env` file that Compose reads automatically. Generate a random value: ```bash echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" | sudo tee /opt/keycloak/.env > /dev/null echo "KC_ADMIN_PASSWORD=$(openssl rand -hex 16)" | sudo tee -a /opt/keycloak/.env > /dev/null sudo chmod 600 /opt/keycloak/.env ``` Print the file once and save the admin password somewhere safe; you need it to log in: ```bash sudo cat /opt/keycloak/.env ``` Now create the Compose file: ```bash sudo nano /opt/keycloak/compose.yaml ``` ```yaml services: postgres: image: postgres:16 environment: POSTGRES_DB: keycloak POSTGRES_USER: keycloak POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - postgres-data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"] interval: 10s retries: 5 restart: unless-stopped keycloak: image: quay.io/keycloak/keycloak:26.4 command: start depends_on: postgres: condition: service_healthy environment: KC_DB: postgres KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak KC_DB_USERNAME: keycloak KC_DB_PASSWORD: ${POSTGRES_PASSWORD} KC_HOSTNAME: https://auth.example.com KC_HTTP_ENABLED: "true" KC_PROXY_HEADERS: xforwarded KC_HEALTH_ENABLED: "true" KC_BOOTSTRAP_ADMIN_USERNAME: admin KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD} ports: - "127.0.0.1:8080:8080" - "127.0.0.1:9000:9000" restart: unless-stopped volumes: postgres-data: ``` A few points about this configuration: - `start` runs Keycloak in production mode, which requires a hostname and TLS. TLS is terminated by Nginx, so `KC_HTTP_ENABLED` allows plain HTTP between Nginx and the container, and `KC_PROXY_HEADERS: xforwarded` tells Keycloak to trust the `X-Forwarded-*` headers Nginx sends. - Ports are bound to `127.0.0.1`, so Keycloak is only reachable through Nginx. Port 9000 is the management interface that serves health checks. - The image is pinned to a release line. Check the [Keycloak releases](https://www.keycloak.org/downloads) page for the current version before deploying. Start the stack. Run this and every other `docker compose` command in this guide from `/opt/keycloak`: ```bash cd /opt/keycloak sudo docker compose up -d ``` The first start takes a minute or two while Keycloak builds its configuration and creates the database schema. Wait until the readiness endpoint reports `UP`: ```bash curl -s http://127.0.0.1:9000/health/ready ``` ```output { "status": "UP", "checks": [ ... ``` If it does not come up, read the logs with `sudo docker compose logs keycloak`. ## Step 3 - Configuring Nginx and HTTPS Create an Nginx server block that forwards requests to Keycloak: ```bash sudo nano /etc/nginx/sites-available/keycloak ``` ```nginx server { listen 80; listen [::]:80; server_name auth.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port; # Keycloak sends large cookies and headers proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; } } ``` Enable the site and test the configuration: ```bash sudo ln -s /etc/nginx/sites-available/keycloak /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx ``` Request a certificate. Certbot edits the server block to listen on 443 and redirect HTTP to HTTPS: ```bash sudo certbot --nginx -d auth.example.com --redirect ``` Verify that Keycloak answers over HTTPS with the correct issuer: ```bash curl -s https://auth.example.com/realms/master/.well-known/openid-configuration | grep -o '"issuer":"[^"]*"' ``` ```output "issuer":"https://auth.example.com/realms/master" ``` Open `https://auth.example.com/admin/` in a browser and log in as `admin` with the `KC_ADMIN_PASSWORD` value from `/opt/keycloak/.env`. > Important: The bootstrap admin is meant to be temporary. In the `master` realm, create a personal administrator under **Users**, assign it the `admin` role, log in with it, and then delete the `admin` bootstrap user. ## Step 4 - Creating a realm A realm is an isolated space with its own users, clients and login settings. Keep the `master` realm for Keycloak administration only and create a separate realm for your applications. You can do this in the admin console (realm drop-down, **Create realm**) or with the `kcadm.sh` CLI inside the container, which is easier to repeat. Log the CLI in. It prompts for the admin password: ```bash sudo docker compose exec keycloak /opt/keycloak/bin/kcadm.sh config credentials \ --server http://localhost:8080 --realm master --user admin ``` ```output Logging into http://localhost:8080 as user admin of realm master Enter password: ``` Create the realm `myapp`: ```bash sudo docker compose exec keycloak /opt/keycloak/bin/kcadm.sh create realms \ -s realm=myapp -s enabled=true -s loginWithEmailAllowed=true -s resetPasswordAllowed=true ``` ```output Created new realm with id 'myapp' ``` ## Step 5 - Registering an OIDC client Each application that signs users in through Keycloak is a client. Create a confidential OIDC client for a web application at `https://app.example.com`. Service accounts are enabled so you can test token issuance from the command line: ```bash sudo docker compose exec keycloak /opt/keycloak/bin/kcadm.sh create clients -r myapp \ -s clientId=my-webapp \ -s protocol=openid-connect \ -s publicClient=false \ -s standardFlowEnabled=true \ -s serviceAccountsEnabled=true \ -s 'redirectUris=["https://app.example.com/*"]' \ -s 'webOrigins=["https://app.example.com"]' \ -i ``` The `-i` flag prints the internal ID of the new client: ```output 6f1c2d8a-3b4e-4f5a-9c7d-1e2f3a4b5c6d ``` Use that ID to read the generated client secret: ```bash sudo docker compose exec keycloak /opt/keycloak/bin/kcadm.sh get \ clients/6f1c2d8a-3b4e-4f5a-9c7d-1e2f3a4b5c6d/client-secret -r myapp ``` ```output { "type" : "secret", "value" : "Jk3vQ0bY7hH1pW9sXz2mL8cN5tR4aE6d" } ``` Test the client with the client credentials grant. A JSON response with an `access_token` proves the realm, client and secret are correct: ```bash curl -s -X POST https://auth.example.com/realms/myapp/protocol/openid-connect/token \ -d grant_type=client_credentials \ -d client_id=my-webapp \ -d client_secret=your_client_secret | head -c 120; echo ``` ```output {"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ4b0xrQ3N... ``` ## Step 6 - Creating a user Create a user in the `myapp` realm and set a temporary password that must be changed at first login: ```bash sudo docker compose exec keycloak /opt/keycloak/bin/kcadm.sh create users -r myapp \ -s username=jsmith -s email=jsmith@example.com -s firstName=John -s lastName=Smith \ -s emailVerified=true -s enabled=true sudo docker compose exec keycloak /opt/keycloak/bin/kcadm.sh set-password -r myapp \ --username jsmith --new-password 'your_temporary_password' --temporary ``` Verify by signing in to the realm's account console at `https://auth.example.com/realms/myapp/account/`. Keycloak asks `jsmith` to choose a new password and then shows the account page. ## Step 7 - Connecting an application Most frameworks and tools only need the realm's issuer URL, the client ID and the client secret; they read everything else from the discovery document at `https://auth.example.com/realms/myapp/.well-known/openid-configuration`. The individual endpoints are: | Purpose | URL | |---|---| | Issuer | `https://auth.example.com/realms/myapp` | | Authorization | `/realms/myapp/protocol/openid-connect/auth` | | Token | `/realms/myapp/protocol/openid-connect/token` | | User info | `/realms/myapp/protocol/openid-connect/userinfo` | | Signing keys (JWKS) | `/realms/myapp/protocol/openid-connect/certs` | | Logout | `/realms/myapp/protocol/openid-connect/logout` | In the application, configure the redirect (callback) URL so it matches one of the `redirectUris` you registered, for example `https://app.example.com/oauth2/callback`. For applications that only speak SAML 2.0, create a client with the **SAML** protocol in the admin console and give the application Keycloak's identity provider metadata, published at: ```text https://auth.example.com/realms/myapp/protocol/saml/descriptor ``` To authenticate users stored in an existing LDAP or Active Directory server, open the realm in the admin console, go to **User federation**, add an **LDAP** provider, enter the connection URL, bind DN and users DN, and use **Test connection** and **Test authentication** before saving. ## Step 8 - Backing up the database All realms, clients and users live in PostgreSQL. Take a logical dump with `pg_dump` from the database container: ```bash sudo docker compose exec -T postgres pg_dump -U keycloak keycloak | gzip > ~/keycloak-$(date +%F).sql.gz ``` Check that the file is not empty: ```bash ls -lh ~/keycloak-*.sql.gz ``` Schedule this command with cron or a systemd timer and copy the dumps off the server. ## Troubleshooting **The admin console shows "HTTPS required" or redirects to `http://`.** Nginx is not sending `X-Forwarded-Proto`, or `KC_PROXY_HEADERS` is missing. Check both, then run `sudo docker compose up -d` to recreate the container. **`Invalid parameter: redirect_uri` on login.** The redirect URL the application sends must match one of the client's **Valid redirect URIs** exactly, including the scheme and trailing path. A pattern ending in `/*` matches any path below it. **`502 Bad Gateway` from Nginx.** Keycloak is still starting or has crashed. Check `sudo docker compose ps` and `sudo docker compose logs --tail 50 keycloak`. Database authentication errors usually mean `.env` was changed after the PostgreSQL volume was created; the database keeps its original password. **`upstream sent too big header` in `/var/log/nginx/error.log`.** Increase `proxy_buffer_size` and `proxy_buffers` in the server block. ## Conclusion Keycloak now runs on Ubuntu 24.04 with PostgreSQL storage, HTTPS through Nginx, a dedicated realm, a confidential OIDC client and a test user. From here you can put internal tools behind it with OAuth2 Proxy, enable one-time password or passkey policies under **Authentication**, and connect your existing LDAP directory through user federation.