What is Keycloak: SSO, OAuth 2.0, and open-source account management

What is Keycloak

Keycloak is an open-source identity server: it handles user login, account storage and issuance of permissions for your applications. It exists so you don’t have to implement authorization in every service separately: a user logs in once (SSO), and applications receive confirmation from Keycloak via standard protocols OpenID Connect, OAuth 2.0 or SAML 2.0.

The project is distributed under the Apache 2.0 license, runs on the Quarkus platform and is part of the Cloud Native Computing Foundation as an incubating project. The current version as of September 2026 is 26.7.4.

What it can do

• Single sign-on (SSO). A user signs in once and gets access to all connected applications; logout can also be global.
• Standard protocols. OpenID Connect and OAuth 2.0 for web and mobile applications and APIs, SAML 2.0 for enterprise systems that do not support OIDC.
• Multi-factor authentication. One-time codes from an authenticator app (TOTP), hardware keys and device keys via the WebAuthn standard.
• Login via external providers. Google, GitHub, corporate SAML or OIDC providers, as well as Active Directory and LDAP — Keycloak can take users from an existing directory without migrating them.
• Roles and groups. Permissions are set at the realm level and per-client level and are passed to the application in the token.
• Extensibility. Login page themes and custom providers via Service Provider Interfaces (SPI).

Main concepts

• Realm — an isolated space with its own users, clients and settings. The service realm master is intended only for administration; create a separate realm for applications.
• Client — an application that trusts Keycloak for user login. For a web application with a server use a confidential client with a secret; for a single-page application and mobile app use a public client with PKCE.
• Roles exist at the realm level (global) and at the client level (for a specific application). It’s more convenient to assign roles to groups rather than to individual users.

How to run

To get started, one command from the official guide is enough — it starts Keycloak in development mode with an admin account:

docker run -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.7.4 start-dev

The start-dev mode is not suitable for production: it stores data in the built-in dev-file database, which, according to the documentation, is intended only for development, and it does not require HTTPS. For a production installation you need:

• an external database — PostgreSQL, MySQL, MariaDB, Oracle or Microsoft SQL Server (parameters --db, --db-url-host, --db-username, --db-password);
• server address — in production the --hostname parameter is required (preferably a full URL) or explicitly --hostname-strict false;
• TLS — certificate and key in PEM format (--https-certificate-file, --https-certificate-key-file) or TLS termination on a reverse proxy; in the latter case you need --http-enabled=true and --proxy-headers xforwarded (or forwarded).

Example of running behind a reverse proxy that terminates TLS:

bin/kc.sh start \
  --hostname https://sso.example.ru \
  --db postgres --db-url-host db.internal \
  --db-username keycloak --db-password 'long-password' \
  --http-enabled=true --proxy-headers xforwarded

The documentation recommends exposing only the paths /realms/, /resources/ and /.well-known/ to the outside, while keeping the admin console /admin/, the service realm /realms/master/, and /metrics and /health accessible only from the internal network.

Limitations

• Administration. Keycloak is another critical service: it needs to be updated (new versions are released frequently), backed up together with the database and monitored. If it is unavailable, users cannot log into any application.
• Resources. This is a Java application: it requires more memory than lightweight authentication servers, and it will struggle on the cheapest VPS.
• Learning curve. There are many settings and some are non-obvious: token and session lifetimes, client types, redirect URIs, attribute mapping when connecting LDAP.

Common mistakes

• Running production installation in start-dev mode with the built-in database.
• Putting applications in the master realm and exposing the admin console to the internet.
• Using wildcard Redirect URI (https://example.ru/* or just *) — this allows redirecting a token to a third-party page.
• Not backing up the Keycloak database: losing it removes all users, clients and settings.
• Upgrading across multiple versions at once without reading migration notes.

When to choose

Keycloak is suitable if a company has several internal or customer-facing applications, needs single sign-on, two-factor authentication and integration with Active Directory or LDAP, and user data must remain on in-house servers — including in Russia, where since July 1, 2025 the primary collection of personal data of citizens is allowed only in databases located on the territory of the country. For a single small site with social login it is excessive.

If you need help with installation and connecting applications, see the Keycloak and SSO setup service.