What is Keycloak and do you actually need it?
Single sign-on sounds like enterprise territory — but Keycloak runs in Docker on a Raspberry Pi and solves real problems for small teams and homelabs.
TL;DR
Keycloak is a free, open-source identity and access management (IAM) server. Run it in Docker and you get single sign-on (SSO), user registration, role-based access control, and support for standard protocols including OAuth 2.0, OpenID Connect (OIDC), and SAML 2.0 — for any number of your own apps.
If you have more than one internal app and you're tired of managing separate logins for each, Keycloak solves that in an afternoon.
What you'll need
- A server or machine running Docker (a Raspberry Pi 4 with 4 GB RAM is enough for a homelab)
- A domain name if you want HTTPS (required for anything beyond local testing)
- About 30 minutes for a first read-through; an hour to have it running
What Keycloak actually does
When a user tries to access one of your apps, the app redirects them to Keycloak's login page instead of handling the login itself. Keycloak authenticates the user, then sends a token back to the app confirming who they are and what they're allowed to do. The app never sees the password.
This means:
- One login for all your apps. Users log in once and access everything — no separate passwords per service.
- Centralised user management. Add, disable, or reset a user in one place and it applies everywhere.
- Multi-factor authentication (MFA). Enable TOTP (Google Authenticator, Authy) or WebAuthn (passkeys) for all your apps in one go.
- Social login. Let users log in with Google, GitHub, or Microsoft without building it yourself.
- Fine-grained access control. Assign roles and restrict which users can access which apps.
When you probably need it
- You're running a homelab with Nextcloud, Gitea, Grafana, Jellyfin, and similar tools — and managing separate accounts for each is becoming a mess.
- Your small business uses self-hosted apps and you want a proper SSO solution without paying for Okta or Azure AD P1.
- You're building a web app and need user authentication with OAuth2/OIDC without writing it from scratch.
When you probably don't
- You have only one app. The overhead of running Keycloak isn't worth it for a single service.
- You're a complete beginner with Docker. Get comfortable with containers first — Keycloak has moving parts.
- You need it running on a £5/month shared host. Keycloak needs at least 512 MB RAM and a proper container runtime.
The core concepts
Realm — A namespace that groups users, apps, and settings together. You'll typically create one realm per organisation or project (not one per app). The built-in "master" realm is for Keycloak administration only — don't use it for your apps.
Client — A registered application that Keycloak knows about. Each app (Nextcloud, your Node.js API, Grafana) gets its own client configuration.
User — A person with an account in Keycloak's user database. Users belong to a realm.
Role — A label you assign to users to control what they can access. Apps can check roles from the token Keycloak issues.