Keycloak
Keycloak is an open-source identity and access management (IAM) solution that provides single sign-on (SSO), authentication, authorization, and user federation capabilities for modern applications and services.[1] Developed to simplify security integration, it enables developers to secure web and mobile applications without building custom user management systems, supporting standards such as OpenID Connect, OAuth 2.0, and SAML 2.0.[2] Originally initiated as a community project associated with JBoss technologies, Keycloak has evolved into a widely adopted tool maintained by an active open-source community under the Cloud Native Computing Foundation (CNCF) umbrella.[3] At its core, Keycloak operates as a standalone server that handles user authentication and issues secure tokens containing identity and permissions data, allowing applications to verify access without storing sensitive user information.[2] Key features include identity brokering for integrating with social networks or existing identity providers, user federation with LDAP or Active Directory, fine-grained authorization services, and customizable user interfaces for login, registration, and account management.[1] It supports high availability through clustering, theming for branding, and extensibility via service provider interfaces (SPIs) for custom functionality.[2] Keycloak's architecture revolves around realms, isolated spaces for managing users, clients, and roles, which facilitates multi-tenancy and secure separation of concerns across different applications or organizations.[2] The solution includes an administrative console for central configuration of realms, users, and policies, as well as an account console where users can manage their profiles, sessions, and two-factor authentication setups.[1] Deployable via containers like Docker or on platforms such as Kubernetes, it emphasizes performance and scalability for enterprise environments.[4]Overview
Introduction
Keycloak is an open-source identity and access management (IAM) solution designed to add authentication and authorization to applications and services with minimal configuration.[1][2] Its primary purpose is to enable single sign-on (SSO), centralized user management, and secure access control, allowing applications to delegate identity handling rather than implementing it internally.[2][3] This approach reduces the complexity of security implementation for developers, providing ready-to-use features such as customizable login interfaces, user registration, and account management.[2] Keycloak targets modern use cases including web applications, RESTful web services, microservices architectures, and cloud-native environments, where scalable and integrated identity solutions are essential.[2][3] It supports seamless integration with existing identity providers like LDAP, Active Directory, and social platforms such as Facebook and Google, facilitating user federation and social login.[2] Key benefits include accelerated development by offloading security concerns, enhanced scalability for distributed systems, and support for standards like OpenID Connect and OAuth 2.0 to ensure interoperability.[2][3] By centralizing role-based access control and token-based authentication, it promotes secure, efficient management across diverse ecosystems.[2]Licensing and Development
Keycloak is distributed under the Apache License 2.0, a permissive open-source license that allows users to freely use, modify, and distribute the software for any purpose, provided that copyright notices and the license terms are preserved in all copies or substantial portions of the software.[5] This licensing model encourages widespread adoption while ensuring compatibility with both open-source and proprietary projects. The development of Keycloak is primarily maintained by Red Hat, which sponsors the project as part of its JBoss community initiatives, with core contributions and oversight provided by a dedicated team of maintainers.[6] Contributions from the broader developer community are welcomed and integrated through pull requests on the project's GitHub repository, following a contributor guide that emphasizes code quality, testing, and adherence to the Developer Certificate of Origin. This collaborative model has fostered steady evolution, with maintainers reviewing and merging enhancements that align with the project's roadmap.[7] The Keycloak community comprises developers and organizations worldwide who actively participate via discussion forums, issue trackers, and annual events such as KeycloakCon—a half-day conference co-located with KubeCon—and Keycloak DevDay, which feature technical talks, workshops, and networking opportunities.[8] Red Hat bolsters this ecosystem with enterprise-grade support through its Red Hat build of Keycloak, a downstream distribution offering long-term stability, security updates, and certified integrations for production environments.[9] Project governance is handled by the maintainers, who prioritize features, manage releases, and ensure alignment with community needs.[10] In April 2023, Keycloak joined the Cloud Native Computing Foundation (CNCF) as an incubating project, and remains an incubating project as of November 2025, promoting its adoption in cloud-native architectures through alignment with Kubernetes, OpenTelemetry, and other CNCF standards for scalable, resilient identity management.[11][12]History
Origins and Early Development
Keycloak originated in 2013 as an open-source project initiated by developers within the JBoss community at Red Hat, aimed at filling gaps in available single sign-on (SSO) solutions tailored for Java-based applications and services.[13] The project was co-led by Bill Burke and Stian Thorgersen, with contributions from a core team including Gabriel Cardoso, Viliam Rockai, Bolesław Piech, and Alexandre Mendonça, all affiliated with Red Hat's JBoss division.[13] The primary motivations for Keycloak's creation were to provide a lightweight, standards-compliant alternative to proprietary identity and access management (IAM) tools, emphasizing ease of integration for browser applications, RESTful services, and social authentication providers.[13] Drawing inspiration from the existing PicketLink project—particularly its federation capabilities—the developers sought to extend beyond PicketLink's primary focus on SAML to incorporate broader support for protocols like OAuth 2.0, while leveraging PicketLink components where appropriate.[13] This approach addressed the need for centralized user authentication, authorization, and management in modern web and mobile ecosystems without relying on vendor lock-in.[13] Early development commenced with prototyping in July 2013, building on prior work from the RESTEasy project's OAuth module and a social broker service.[13] The first alpha release followed in December 2013, prioritizing OAuth 2.0 bearer token support, social login integrations (such as Google and Facebook), user self-registration, and an administrative console.[13] Keycloak achieved production readiness with its inaugural stable release, version 1.0, on September 18, 2014, which stabilized database schemas, enhanced performance, and refined service provider interfaces (SPIs) to enable reliable basic SSO deployments. This milestone marked the project's maturation from experimental code to a deployable solution compatible with JBoss AS7, EAP 6.x, and WildFly servers.Major Releases and Milestones
Keycloak's development has seen steady evolution through major version releases, each introducing significant enhancements to its identity and access management capabilities. The project began with its first production release in September 2014, but major milestones from 2015 onward marked key advancements in protocol support, runtime improvements, and enterprise integrations.[14] The first major version, 2.0.0, released in February 2015, introduced enhanced support for SAML 2.0, enabling broader federation with legacy systems alongside its core OpenID Connect and OAuth 2.0 features. In 2016, Red Hat integrated Keycloak as the upstream project for Red Hat Single Sign-On (RH-SSO) 7.0, providing enterprise support and aligning community development with commercial offerings for improved stability and security patching. Version 10.0.0, released in April 2020, brought the new account management console, allowing users to self-manage profiles, sessions, and applications through a modern, customizable interface. A pivotal shift occurred with version 15.0.0 in July 2021, which previewed a Quarkus-based distribution to replace the legacy WildFly runtime, delivering substantial performance gains, faster startup times, and better resource efficiency for containerized deployments. By 2020, Keycloak had achieved widespread adoption, powering authentication in major Kubernetes ecosystems via integrations like oauth2-proxy and native operators, as well as cloud platforms such as AWS and Azure for SSO services. In July 2023, version 22.0.0 completed the migration to Jakarta EE from Java EE, updating the codebase to support modern enterprise Java standards and ensuring compatibility with Quarkus 3.x for enhanced modularity.[15] In April 2023, Keycloak was accepted into the Cloud Native Computing Foundation (CNCF) as an incubating project.[11] The 26.x series, starting with 26.0.0 in October 2024, focused on compliance and emerging standards, including experimental support for OpenID for Verifiable Credential Issuance (OID4VCI), enabling credential issuance flows for decentralized identity use cases.[16] As of November 2025, releases like 26.4.0 in September 2025 emphasized high-availability clustering improvements, such as optimized multi-site architectures with persistent user sessions by default, full compliance with FAPI 2.0 Security Profile and Message Signing, and official support for Demonstrating Proof-of-Possession (DPoP) to support large-scale deployments.[17]| Version | Release Date | Key Milestones |
|---|---|---|
| 2.0.0 | February 2015 | SAML 2.0 federation support |
| RH-SSO 7.0 | June 2016 (aligned with Keycloak 1.9) | Red Hat enterprise integration |
| 10.0.0 | April 2020 | Account management console introduction |
| 15.0.0 | July 2021 | Quarkus runtime preview for performance |
| 22.0.0 | July 2023 | Jakarta EE migration |
| CNCF Incubating | April 2023 | Acceptance into CNCF |
| 26.0.0 | October 2024 | OID4VCI experimental |
| 26.4.0 | September 2025 | FAPI 2.0 compliance, HA clustering enhancements, DPoP support |
Core Concepts
Realms and Isolation
In Keycloak, a realm serves as the foundational logical isolation boundary, encapsulating a set of users, clients (applications), roles, groups, and authorization policies within a single namespace that functions similarly to a tenant in multi-tenant architectures.[2] This structure ensures that resources and configurations within one realm remain segregated from others, preventing unauthorized access or data leakage across boundaries and thereby enhancing security in shared deployments.[18] Users authenticate and log into a specific realm, which manages their credentials and associated entities exclusively.[2] Each realm supports independent configuration options, including authentication flows, login themes, email settings, SSL modes, and identity providers, allowing administrators to tailor behaviors without affecting other realms.[19] The master realm, a default administrative realm created upon initial setup, is reserved exclusively for managing realms and performing system-wide administrative tasks, such as creating new realms or configuring global server settings; it does not handle end-user authentication.[18] This separation promotes multi-tenancy by enabling a single Keycloak instance to support distinct environments, such as development versus production, or isolated customer partitions, where data and policies for one tenant (e.g., an enterprise's internal users) do not intersect with another (e.g., external partners).[20] Realm management occurs primarily through the Keycloak Admin Console, where administrators can create new realms via a simple form-based interface, specifying a unique name and initial settings.[21] For migration or replication purposes, realms can be exported as JSON files—either individually from the Admin Console or in bulk via command-line tools like the Keycloak CLI—capturing the full configuration including users, clients, roles, and policies; these files can then be imported into another instance, though exports from the console are not recommended for production backups due to potential inconsistencies during large-scale operations.[22] Within a realm, clients and users interact as core entities, with clients representing applications that request authentication and users being the authenticated principals assigned roles for access control.[2]Clients, Users, and Roles
In Keycloak, clients represent applications or services that register with a realm to leverage its authentication and authorization capabilities. These entities are configured with essential attributes such as a unique client ID, a human-readable name, and an access type—typically confidential for server-side applications requiring client secrets, public for browser-based or mobile apps without secrets, or bearer-only for services that do not initiate authentication but validate tokens. Additional configurations include valid redirect URIs to prevent open redirect attacks, protocol selection (e.g., OpenID Connect or SAML), and token settings like access token lifespans. Clients can also define their own scopes, which bundle permissions or claims to request during authentication flows.[2] Users in Keycloak are individual accounts managed within a specific realm, serving as the primary entities that authenticate and access protected resources. Key attributes include a unique username, email address, first name, last name, and credentials such as passwords or one-time passwords (OTP) for multi-factor authentication. Users support self-registration if enabled in realm settings, and their profiles can be customized via attribute schemas that define required fields, validations (e.g., email format), and permissions for viewing or editing attributes in contexts like registration or the account console. Session management tracks active user sessions, with features like consent screens allowing users to approve client access to their profile data before token issuance. Required actions, such as password resets or email verification, can be enforced per user or as defaults during login.[2] Roles in Keycloak provide a mechanism for role-based access control (RBAC), categorizing permissions that dictate what users or clients can do within a realm. There are three main types: realm roles, which apply globally across the realm (e.g., "admin" for broad administrative privileges); client roles, which are namespaced to a specific client for granular control (e.g., "editor" within a particular application); and composite roles, which inherit permissions from other roles to simplify management (e.g., a "manager" composite including both "viewer" and "editor" roles). Roles include basic attributes like name and description, and they can be assigned directly to users or inherited via group membership. Client-specific roles are managed under each client's settings in the admin console, ensuring isolation from other clients.[2] The interplay among clients, users, and roles enables fine-grained access control within a realm, which acts as the isolation boundary for these entities. Users are assigned roles through the role mappings tab in their profile, granting them permissions that are evaluated during authentication; for instance, a user with the "admin" realm role might access administrative endpoints across multiple clients. Clients request specific scopes during token issuance, which map to roles—only users possessing the corresponding roles receive tokens with the approved scopes, enforcing authorization at the application level. This relationship supports consent mechanisms, where users explicitly approve role-based access, and service accounts on clients can impersonate roles for machine-to-machine interactions without user involvement. Composite roles streamline assignments by propagating permissions hierarchically, reducing administrative overhead while maintaining security.[2]Architecture
Server Components
The Keycloak server features a web-based Admin Console that serves as the primary interface for administrators to manage realms, configure users and roles, and audit events. Accessible typically athttp://[localhost](/page/Localhost):8080/admin/ after logging in with administrative credentials, it provides tools for creating and isolating realms, assigning roles to users and clients, and viewing event logs for activities such as logins, logouts, and administrative changes.[23] The console supports customization through themes and includes sections for user management, such as required actions like password resets, and session monitoring to ensure secure oversight of the identity provider's operations.[24]
Complementing the Admin Console is the Account Management Console, a user-facing portal designed for self-service tasks that empowers end-users to manage their own accounts without administrative intervention. Users access it via a realm-specific URL, such as http://localhost:8080/realms/{realm-name}/account, where they can update personal profiles, reset passwords, configure two-factor authentication like OTP, view active sessions, and manage linked identity providers or federated accounts.[25] Features like account deletion and credential management can be enabled or restricted by administrators through realm settings, ensuring compliance with organizational policies while promoting user autonomy.[26]
At the backend, Keycloak includes essential services such as the token endpoint, which handles OAuth 2.0 and OpenID Connect flows by issuing access tokens, ID tokens, and refresh tokens upon successful authentication. This endpoint, located at /realms/{realm}/protocol/openid-connect/token, supports grant types like authorization code, client credentials, and resource owner password credentials, allowing clients to securely obtain tokens for API access or user sessions with configurable expiration times, such as the default of five minutes for access tokens.[27][28] Event listeners provide logging and auditing capabilities by capturing and processing events such as user registrations, logins, and admin actions, which can be stored in the database or forwarded to external systems for compliance and security monitoring; predefined listeners like jboss-logging output to server logs, while custom ones can be developed for specialized needs.[29] The Service Provider Interface (SPI) enables extensibility by allowing developers to implement custom providers for authentication, themes, or user storage, deployed as JAR files in the providers/ directory followed by a server build command like bin/kc.sh build.[30]
For storage, Keycloak defaults to an Infinispan cache to manage user sessions, tokens, and transient data efficiently in memory, optimizing performance for high-traffic scenarios while supporting clustering for distributed environments.[31] It also accommodates external relational databases like PostgreSQL for persistent storage of realms, users, and events, configured via properties such as db=postgres, db-url, db-username, and db-password in keycloak.conf or environment variables, with JDBC drivers required for connectivity to ensure data durability beyond in-memory caching.[32] This hybrid approach balances speed with reliability, allowing administrators to switch storage backends without altering core server logic.
Deployment and Scalability
Keycloak supports multiple deployment modes to accommodate various environments, from simple setups to complex, containerized infrastructures. The standalone JAR distribution allows deployment on physical or virtual servers using OpenJDK, where administrators download and run the JAR file directly for quick prototyping or small-scale use.[33] For containerized environments, Keycloak provides official Docker images optimized for production, enabling easy integration with orchestration tools and CI/CD pipelines.[34] In Kubernetes clusters, the Keycloak Operator facilitates automated deployment, scaling, and management, handling tasks like custom resource definitions for realms and high availability configurations.[35] Since version 17, Keycloak has transitioned to a Quarkus-based distribution, supporting native compilation for reduced memory footprint and faster startup times, which enhances performance in resource-constrained settings.[36] For production environments, Keycloak requires specific configurations to ensure security, reliability, and performance. HTTPS enforcement is mandatory, achieved by configuring TLS certificates and enabling strict transport security via thekc https-certificate options or reverse proxy integration.[37] Hostname configuration sets the public-facing URL for endpoints, with best practices recommending separate hostnames or paths for administrative interfaces to isolate them from user-facing services.[38] Database tuning involves selecting a robust relational database like PostgreSQL, optimizing connection pools, and enabling features such as prepared statements to handle high query loads.[39] Caching is configured using the embedded Infinispan for local sessions or external stores like Redis for distributed persistence, reducing database strain in multi-node setups.[40]
Scalability in Keycloak is achieved through clustering and horizontal expansion to manage high traffic and ensure high availability. Clustering relies on JGroups for node discovery and communication, integrated with Infinispan for distributed caching of sessions, realms, and authentication data across nodes.[40] Horizontal scaling involves deploying multiple instances behind a load balancer, where throughput scales linearly until bottlenecks in the database or cache occur; Kubernetes deployments can use Horizontal Pod Autoscalers to dynamically adjust replicas based on CPU or custom metrics.[41] Metrics export to Prometheus is built-in, allowing monitoring of key indicators like request latency, error rates, and cache hit ratios to inform scaling decisions.[42]
As of 2025, best practices for Keycloak deployments emphasize IPv6 dual-stack support, which is enabled by default for broader network compatibility without additional configuration.[43] Zero-downtime upgrades are recommended using rolling updates via the Kubernetes Operator, ensuring seamless transitions between patch releases by maintaining active nodes during the process.[44]