Keycloak: Open Source Identity and Access Management

What Keycloak is

Keycloak is an open-source identity and access management server. Its pitch, repeated on both the GitHub README and the project site, is to add authentication to applications and secure services with minimum effort, so that application teams no longer have to store users or authenticate them themselves. Instead of every service shipping its own login form, password table and session handling, applications hand that job to Keycloak and trust the tokens it issues.

The project has been around since 2013, is written in Java, is licensed under Apache-2.0 and is a Cloud Native Computing Foundation incubation project. Out of the box it covers single sign-on and single sign-out, identity brokering and social login, user federation with LDAP and Active Directory, fine-grained authorization, an admin console and a self-service account console, all built on the standard protocols OpenID Connect, OAuth 2.0 and SAML 2.0.

The audience is broad. Platform teams use it as the central login service for a fleet of internal applications. Product teams use it to give a customer-facing app proper sign-up, social login and two-factor authentication without building those features. Enterprises use it to put modern OIDC-based applications in front of an existing LDAP or Active Directory directory. Anyone who would otherwise reach for a hosted identity provider but wants to run the service on their own infrastructure is in the target group.

How it works

Keycloak runs as a standalone server that applications talk to over standard protocols. A user who tries to reach a protected application is redirected to Keycloak, signs in there, and is sent back with tokens the application can verify. Because the user authenticated with Keycloak rather than the individual application, a second application in the same setup can recognise the existing session and skip the login entirely. Logout works the same way in reverse: the project site describes single sign-out, where logging out once logs the user out of every application that uses Keycloak.

The central organising concept is the realm. The getting-started guide describes a realm as equivalent to a tenant: each one lets an administrator create isolated groups of applications and users. A fresh installation contains a single realm called master, and the docs are explicit that it should be used only for managing Keycloak itself, not for your applications. Inside a realm you register clients (the applications Keycloak protects), create or federate users, and configure identity providers, roles and authorization policies.

Under the hood the server stores its state in a relational database and, when you run more than one node, uses JGroups and Infinispan for clustering and distributed caches. The production guide notes that in the default clustered setup, communication between nodes is encrypted using TLS. Configuration comes from four sources, applied in priority order: command-line parameters, environment variables, the conf/keycloak.conf file (or a user-created configuration file), and a Java KeyStore for sensitive options. The same option can be written in each format, for example --db-url on the command line, KC_DB_URL as an environment variable, or db-url in the config file, with the command line winning when several are set.

Keycloak also distinguishes between build options and runtime configuration options. When you use start or start-dev, the server runs a build step under the covers that applies startup and runtime optimizations. For containers and Kubernetes, the docs recommend running that build explicitly ahead of time, for example as a CI step, then starting the server with --optimized so it skips the build at startup.

Key features

• Single sign-on and single sign-out. Users log in once to Keycloak and can move between applications without logging in again; logging out once logs them out everywhere.
• Standard protocols. Support for OpenID Connect, OAuth 2.0 and SAML 2.0, so most frameworks and off-the-shelf software that speak those protocols can integrate without Keycloak-specific code.
• Identity brokering and social login. Social network login is enabled from the admin console by selecting the provider; Keycloak can also delegate authentication to existing OpenID Connect or SAML 2.0 identity providers, again through configuration rather than application changes.
• User federation. Built-in support for connecting to LDAP or Active Directory servers, plus the option to implement your own provider for users stored elsewhere, such as a relational database.
• Admin console. A web UI where administrators manage realms, clients, identity brokering, user federation, users, permissions, sessions and fine-grained authorization policies.
• Account management console. A self-service UI where users update their profile, change passwords, set up two-factor authentication, manage sessions, view account history and link additional identity providers.
• Authorization services. For cases where role-based access control is not enough, Keycloak provides fine-grained authorization so permissions for services can be managed centrally from the admin console.
• Themes, password policies and extensibility. The project lists customisable themes for the look and feel, configurable password policies, and extension through code via providers.
• Feature flags. Optional functionality is packaged as features that can be enabled or disabled at build time, for example with --features or a single --feature-<name>=enabled option. Preview features are disabled by default and are not recommended for production.
• Clustering and high availability. Multiple nodes share sessions through Infinispan so users can keep logging in when an instance goes down.

Getting started

The GitHub README offers two quick routes. Download the distribution from the Keycloak website, unzip it, and run:

bin/kc.[sh|bat] start-dev

Or use the container image:

docker run quay.io/keycloak/keycloak start-dev

The Docker getting-started guide on keycloak.org gives a fuller version of the same container command. It adds -p 127.0.0.1:8080:8080 to publish the port on localhost only, sets the KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD environment variables (both admin in the guide) to create an initial administrator, and pins the image tag to the current release, 26.8.1 at the time of writing, before passing start-dev.

That starts Keycloak on local port 8080 with an admin user named admin and password admin. From there the guide walks through the usual first steps: log in to the admin console at http://localhost:8080/admin, create a realm (the guide uses myrealm), create a user and set a non-temporary password, then register a first OpenID Connect client with the standard flow enabled. The guide uses a hosted single-page test application on keycloak.org to confirm that the new client can sign a user in.

The start-dev command runs development mode, which the configuration guide says enables HTTP, disables strict hostname resolution, uses a local cache instead of a distributed one, and turns off theme and template caching. Production mode is started with start and follows a secure-by-default principle: HTTP is disabled, and the server refuses to start until a hostname and HTTPS/TLS are configured. For container deployments, the containers guide shows writing a Containerfile that runs the build step at image-build time, tagging the result (the guide calls it mykeycloak), and running it with start --optimized plus a hostname, so the container starts without rebuilding on every launch.

The initial admin account can be created from the web frontend over a localhost connection, or with the KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD environment variables, which Keycloak reads on first startup. After that, additional users can be managed in the admin console or with the kcadm.[sh|bat] command-line tool.

JVM-level settings are passed through the JAVA_OPTS_APPEND environment variable. The production guide uses it as the example for network stack preferences: by default Keycloak is reachable over IPv4 and IPv6 at the same time, and to restrict it to IPv4 you set:

export JAVA_OPTS_APPEND="-Djava.net.preferIPv4Stack=true"

The same guide covers the remaining production checklist in outline form: TLS for all inbound and outbound traffic, a public hostname configuration, a reverse proxy, a production-grade database, a cluster of at least two nodes with the right firewall ports open between them, and load shedding so the server stays responsive under overload.

Use cases

• Central login for internal tools. A company running dashboards, wikis, CI systems and internal services can register each one as a client in a realm, so employees get a single login and a single logout across everything.
• Customer identity for a SaaS product. A product team can let Keycloak handle sign-up, password resets, social login and two-factor authentication through the account console, and only verify tokens in its own backend.
• Bridging a legacy directory to modern apps. User federation lets newer OIDC- or SAML-based applications authenticate against users who still live in LDAP or Active Directory, without migrating the directory first.
• Brokering external identity providers. Organisations that need to accept logins from partner identity providers can configure those as OpenID Connect or SAML 2.0 brokers in the admin console.
• Multi-tenant platforms. Because a realm behaves like a tenant with its own users and applications, platforms that serve several isolated customer groups can separate them by realm.
• Securing APIs and microservices. Services can accept OAuth 2.0 access tokens issued by Keycloak and, where roles are too coarse, use its authorization services for fine-grained permission decisions.

How it compares

The most common alternative to Keycloak is not another self-hosted server but a hosted identity-as-a-service product. Hosted providers remove the operational work: no database to size, no cluster to run, no upgrades to schedule. Keycloak trades that convenience for control. You run it on your own infrastructure, your user data stays in your own database, and there is no per-user pricing from a vendor, but you take on the work of production configuration, TLS, clustering, backups and upgrades that the production guide lays out.

Against writing authentication into each application, the comparison is more lopsided. Building login, password storage, session handling, social login, two-factor authentication and SAML support per application is a large amount of security-sensitive code; Keycloak packages it behind standard protocols. The cost is an extra moving part in the architecture and a learning curve around realms, clients, flows and protocol details. Teams that only need simple username-and-password login for a single application may find a library inside their framework lighter-weight than running an identity server.

Things to know before adopting

• Development defaults are not production defaults. By default the server uses the dev-file database, which the database guide says exists only for development and must be replaced before production. Production deployments need one of the supported databases: MariaDB, Microsoft SQL Server, MySQL, Oracle Database, PostgreSQL, EnterpriseDB Advanced, Amazon Aurora PostgreSQL, Azure SQL Database or Azure SQL Managed Instance, each with listed supported versions.
• Production mode needs a hostname and TLS. start deliberately refuses to run without them. The production guide also recommends running two or more instances, putting a reverse proxy or load balancer in front, and exposing the admin REST API and console on a different hostname or context path from the public login endpoints, blocking admin APIs at the proxy if they are not meant to be public.
• The master realm is for administration only. Applications and their users belong in separate realms you create.
• Build options are stored in plain text. The configuration guide warns that options persisted by the build command are kept in plain text and must not contain sensitive data such as database passwords, which are runtime options.
• No request queue limit by default. The http-max-queued-requests option is unset out of the box; the production guide recommends setting it so overload produces immediate 503 responses instead of an unbounded queue. It also recommends health checks on /health/ready, because the server can open its endpoints while long database migrations are still running in the background.
• Supported platforms. The supported-configurations page lists OpenJDK 17, 21 and 25, bare metal or virtual machines on Linux or Windows, Docker and Podman, and OpenShift 4.18 to 4.21. Other Kubernetes distributions such as Amazon EKS or Azure Kubernetes Service are supported only on a best-effort basis.
• Preview features. Some features, including the technology-preview HTTP serializer that the docs say gives roughly 5% more throughput at the cost of about 6% longer build time, are opt-in and not recommended for production yet.
• WSL caveat. In development mode on Windows Subsystem for Linux the server binds to all network addresses, so a dev instance may be reachable from other machines on the network.
• Licence. Apache-2.0, a permissive licence with no copyleft obligations for applications that integrate with it.

Project activity

As of October 2026 the repository has about 37,600 stars on GitHub and roughly 9,100 forks. It was created in July 2013, is written in Java and is licensed under Apache-2.0. The latest release at the time of writing is 26.8.1, published on 13 October 2026, and commits land on the main branch daily. Container images are published on Quay.io, and the project maintains separate repositories for client libraries, quickstarts and a Node.js adapter. Community help is available through a user mailing list and the CNCF Slack channels, and the project holds community meetings.

Source code and issues are at github.com/keycloak/keycloak, documentation and guides at keycloak.org/documentation, the Docker quick start at keycloak.org/getting-started/getting-started-docker, and the project site at keycloak.org.