Posted inSecurity

Deploying Keycloak with Docker: An All-in-One SSO Solution for Enterprises

Security tutorial - IT technology blog
Security tutorial - IT technology blog

Late Night Stories: When 10 Apps Have 10 Different Passwords

On a fateful Monday night, my phone vibrated incessantly with an urgent message. An admin had just resigned, and I needed to revoke all access permissions immediately. As I started reviewing, I panicked. GitLab had one account, the Wiki another, then Grafana, Jenkins, and a dozen internal dashboards. Every single one had its own separate user database.

Struggling to log into each server to lock accounts in the middle of the night was a wake-up call. Without a centralized Identity Provider (IdP) system, I knew I’d be facing many more sleepless nights. That’s why I turned to Keycloak.

On the Scale: Auth0, Okta, or Self-Hosting Keycloak?

When solving the Identity and Access Management (IAM) puzzle, we usually have three main choices. I carefully considered factors ranging from cost to control before making a decision.

1. Internal Database (The Traditional Way)

  • Pros: Super fast deployment; just add a users table to your existing database.
  • Cons: No Single Sign-On (SSO) functionality. Employees have to remember dozens of passwords. When you need to audit or revoke permissions, you have to go through every single app. It’s exhausting.

2. Cloud IAM (Auth0, Okta, Firebase)

  • Pros: Extremely smooth, world-class security, no server maintenance worries.
  • Cons: Your wallet will “cry” as the number of users grows. Auth0 is only free for the first 7,000 users, then costs escalate rapidly. Additionally, many companies require that user data never leaves their internal infrastructure.

3. Self-hosted Open Source (Keycloak, Casdoor)

  • Pros: 100% data control. Full support for OAuth2, OpenID Connect (OIDC), and SAML 2.0. Most importantly, no license fees.
  • Cons: You are responsible for backups and ensuring the server doesn’t “go down” unexpectedly.

Why is Keycloak the #1 Choice?

I chose Keycloak because it’s a Red Hat-sponsored project and highly reputable. It can connect directly to a company’s existing LDAP or Active Directory. Want users to log in with Google or GitHub? Keycloak handles it in a heartbeat.

Although it’s a bit resource-heavy since it runs on Java (Quarkus), its stability and features are unmatched in the open-source world.

Fast Deployment with Docker Compose

For production, I use PostgreSQL as the database instead of the default H2. Below is the configuration I’m currently using, which helps the system handle load more effectively.

version: '3.8'

services:
  postgres:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: super_strong_password_here
    networks:
      - keycloak_network

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start-dev
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: super_strong_password_here
      KC_HOSTNAME: sso.yourdomain.com
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: super_admin_password
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    networks:
      - keycloak_network

networks:
  keycloak_network:
    driver: bridge

volumes:
  postgres_data:

Pro tip: Never use passwords like 123456. I usually use toolcraft.app/en/tools/security/password-generator to generate a random 32-character string. This tool runs entirely in the browser, making it extremely safe for developers.

Configuring Realms and Clients: Essential Concepts

Once the docker-compose up -d command is finished, you can access the admin interface. Remember: never use the master realm for client applications.

Creating a New Realm

Think of a Realm as a separate “kingdom.” Each project or client should have its own Realm to manage users independently and avoid data confusion.

Setting up Clients

This is where you register the connecting applications. For example, my Dashboard app runs at https://dashboard.internal. I would choose an Access Type of confidential to obtain a Client Secret, raising security to the highest level.

Real-world Lessons (Troubleshooting)

Operating Keycloak isn’t always a bed of roses. I’ve personally dealt with these common issues:

  1. Nginx Headers: If using a Reverse Proxy, you must set X-Forwarded-Proto: https. Without it, Keycloak will refuse to issue tokens, suspecting an insecure connection.
  2. Minimum RAM: Don’t try to run Keycloak on a 512MB VPS. It needs at least 1GB of RAM for a smooth startup. With about 50 simultaneous login requests, RAM usage can spike to 1.5GB.
  3. Timezone Drift: If the server and database clocks differ by more than 5 minutes, OIDC tokens will expire as soon as they are created. Install NTP to ensure accurate time synchronization.

Conclusion

Keycloak hasn’t just made my HR management easier; it has made the entire system much more professional. Enabling Multi-Factor Authentication (MFA) for all applications now takes exactly two clicks.

Instead of letting every app handle its own login, leave that to an “expert” like Keycloak. Wishing you peaceful nights, free from the worries of manual account revocation.

Share:
Tags: