Keycloak: Enterprise Identity Management for Your Homelab

You've got Nextcloud, Gitea, Grafana, Jellyfin, and a dozen other self-hosted services. Each one has its own user database, its own login page, and its own password. You're either reusing the same password everywhere (bad) or maintaining a spreadsheet of per-service credentials (also bad).

Keycloak is an open source identity and access management platform. It gives you one login for all your services — real single sign-on (SSO) with industry-standard protocols.

What Keycloak Does

• Single Sign-On (SSO): Log in once, access all connected services
• User management: Central database of users, groups, and roles
• Identity federation: Connect to external identity providers (Google, GitHub, LDAP, Active Directory)
• Protocol support: OpenID Connect (OIDC), SAML 2.0, OAuth 2.0
• Multi-factor authentication: Built-in TOTP, WebAuthn/FIDO2, and third-party MFA
• Fine-grained authorization: Role-based access control across services
• Social login: Let users authenticate via Google, GitHub, Apple, etc.

Keycloak vs. Authelia vs. Authentik

Choose Keycloak if you need SAML support, identity federation, or fine-grained authorization. Choose Authelia if you just need a login portal in front of your reverse proxy. Choose Authentik if you want a middle ground.

Setup with Docker

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    restart: unless-stopped
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: changeme
      KC_HOSTNAME: auth.yourdomain.com
      KC_PROXY_HEADERS: xforwarded
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: changeme
    ports:
      - 8080:8080
    depends_on:
      keycloak-db:
        condition: service_healthy

  keycloak-db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - keycloak_db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: changeme
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  keycloak_db:

For production, always run behind a reverse proxy with TLS. Keycloak requires HTTPS for most features (it will warn you otherwise).

Reverse Proxy (Caddy)

auth.yourdomain.com {
    reverse_proxy keycloak:8080
}

Initial Configuration

1. Create a Realm

Realms are isolated tenants in Keycloak. The master realm is for admin — create a new realm for your services.

1. Log in to https://auth.yourdomain.com/admin
2. Click the realm dropdown → Create realm
3. Name it homelab (or whatever you prefer)

2. Create Users

In your new realm:

1. Users → Add user
2. Set username, email, first/last name
3. Credentials tab → Set a password
4. Required actions → Optionally force password change on first login

3. Create Groups and Roles

Organize users by function:

• Groups: admins, family, media-users
• Realm Roles: admin, user, media-access

Assign roles to groups, then add users to groups. This scales much better than per-user role assignment.

Connecting Services

OpenID Connect (OIDC)

Most modern self-hosted apps support OIDC. The setup pattern is the same everywhere:

In Keycloak:

1. Go to your realm → Clients → Create client
2. Client type: OpenID Connect
3. Client ID: grafana (or whatever service)
4. Set Valid redirect URIs: https://grafana.yourdomain.com/login/generic_oauth
5. Copy the Client Secret from the Credentials tab

In the service, configure:

• Issuer/Authority URL: https://auth.yourdomain.com/realms/homelab
• Client ID: grafana
• Client Secret: (from Keycloak)
• Scopes: openid profile email

Example: Grafana

# grafana.ini
[auth.generic_oauth]
enabled = true
name = Keycloak
allow_sign_up = true
client_id = grafana
client_secret = your-client-secret
scopes = openid profile email
auth_url = https://auth.yourdomain.com/realms/homelab/protocol/openid-connect/auth
token_url = https://auth.yourdomain.com/realms/homelab/protocol/openid-connect/token
api_url = https://auth.yourdomain.com/realms/homelab/protocol/openid-connect/userinfo
role_attribute_path = contains(realm_access.roles[*], 'admin') && 'Admin' || 'Viewer'

Example: Nextcloud

Install the "Social Login" or "OpenID Connect" app in Nextcloud, then configure:

• Identifier: keycloak
• Client ID: nextcloud
• Client Secret: (from Keycloak)
• Authorize URL: https://auth.yourdomain.com/realms/homelab/protocol/openid-connect/auth
• Token URL: https://auth.yourdomain.com/realms/homelab/protocol/openid-connect/token
• User info URL: https://auth.yourdomain.com/realms/homelab/protocol/openid-connect/userinfo

Example: Gitea

# app.ini
[oauth2]
ENABLED = true

# Then add via Gitea admin UI:
# Authentication Sources → Add OAuth2 Provider
# Provider: OpenID Connect
# Client ID: gitea
# Client Secret: your-secret
# OpenID Connect Auto Discovery URL:
#   https://auth.yourdomain.com/realms/homelab/.well-known/openid-configuration

Services with Good OIDC Support

These self-hosted apps work well with Keycloak out of the box:

• Grafana, Nextcloud, Gitea/Forgejo, Minio, Harbor
• Portainer, ArgoCD, Vault, WikiJS, Outline
• Immich, Paperless-ngx (via proxy auth), Matrix Synapse

SAML for Legacy Apps

Some enterprise tools only support SAML. Keycloak handles both:

1. Clients → Create client
2. Client type: SAML
3. Set the Master SAML Processing URL to the app's ACS endpoint
4. Download the SAML metadata XML from Keycloak and import it into the app

SAML is more complex than OIDC — prefer OIDC whenever the app supports it.

Identity Federation

Connect external identity sources so users can log in with existing credentials:

GitHub Login

1. Identity Providers → Add provider → GitHub
2. Create an OAuth App in GitHub → get Client ID and Secret
3. Users can now "Log in with GitHub" on your Keycloak login page

LDAP / Active Directory

1. User Federation → Add provider → LDAP
2. Configure connection URL, bind DN, user/group search bases
3. Keycloak syncs users from LDAP and authenticates against it

This is powerful for mixed environments — your family logs in with local Keycloak accounts while your work apps authenticate against Active Directory.

Multi-Factor Authentication

Enable MFA in your realm:

1. Authentication → Flows
2. Edit the browser flow to require OTP
3. Or use Required Actions to prompt users to set up TOTP on next login

Keycloak supports:

• TOTP: Google Authenticator, Authy, etc.
• WebAuthn: Hardware keys (YubiKey), fingerprint, Face ID
• Recovery codes: Backup codes for lost devices

Theming

Keycloak's default login page looks corporate. Customize it:

1. Create a theme directory: themes/homelab/login/
2. Override templates and CSS
3. Mount it into the container: -v ./themes:/opt/keycloak/themes
4. Set the realm's login theme to homelab

Or use community themes like Keywind for a modern look.

Common Pitfalls

• Resource usage: Keycloak is a Java application. Give it at least 512 MB RAM, ideally 1 GB. Don't run it on a Raspberry Pi.
• Database is required: SQLite won't cut it. Use PostgreSQL (or MySQL) for any real deployment.
• HTTPS is mandatory: Keycloak refuses to work properly without TLS. Use a reverse proxy.
• Token lifetimes: Default access tokens expire in 5 minutes. Adjust per client if needed, but keep them short for security.
• Backup the database: Keycloak stores all configuration in the database. Back up Postgres regularly.

The Bottom Line

Keycloak is the gold standard for self-hosted identity management. It's what enterprises use, and it's available to your homelab for free. The initial setup is more involved than simpler options like Authelia, but the payoff is real SSO across all your services, identity federation, and enterprise-grade security features.

If you're running more than five services with their own login pages, centralizing authentication with Keycloak will save you time, improve security, and eliminate password fatigue.