What is Keycloak and how to install it step by step

In almost any modern app you use on a daily basis (email, social media, corporate intranets, customer dashboards, etc.) behind the scenes, there's a system that decides who you are and what you can access. When companies start accumulating applications, services, and APIs, manually managing users, passwords, permissions, and sessions becomes a real headache.

Keycloak appears just in time to resolve that messKeycloak is an identity and access management platform that centralizes authentication, authorization, and single sign-on for multiple applications. Instead of each application implementing its own login, role, and password recovery system, Keycloak handles all of that, and applications simply trust it using standards such as OAuth 2.0, OpenID Connect, or SAML 2.0.

What is Keycloak and what role does it play in IAM security?

Keycloak is an open source IdP (Identity Provider)Written in Java and maintained by Red Hat (formerly JBoss), it is licensed under Apache 2.0, so it can be freely used and adapted even in commercial environments. A paid, enterprise-level version called Red Hat Single Sign-On exists, but the core functionality is the same.

This identity server provides SSO, federation, and multi-tenancyIt allows a user to log in once and access multiple applications, with those applications delegating authentication to Keycloak, and the management of users, groups, attributes, and permissions being done centrally, without reimplementing the wheel in each project.

Keycloak stands out from other IAM solutions (free, open source, or proprietary) based on their maturity, adoption, and compatibility with standard protocols. Even so, the right solution for each organization will depend on its needs (commercial support, SLA, specific functionalities, on-premises versus SaaS deployment, etc.).

One of Keycloak's strengths It combines several components: OAuth 2.0 and OpenID Connect based authentication, SAML 2.0 support, social login (Google, Facebook, GitHub, etc.), integration with LDAP and Active Directory, administration via web console, CLI and REST API, as well as a flexible model of users, groups and roles that are reflected in the tokens issued for the applications.

Required foundations: OAuth 2.0, OpenID Connect and JWT

To fully understand what Keycloak does, it's helpful to have three concepts clear.OAuth 2.0, OpenID Connect (OIDC), and JSON Web Tokens (JWT). You don't need to become an expert, but you do need to understand the general concept, because everything revolves around them.

OAuth 2.0 as an authorization framework

OAuth 2.0 is a standard API authorization frameworkUsed by giants like Google, Facebook, Microsoft, GitHub, and LinkedIn, its main function is to allow an application (client) to access a user's resources in another application or API, with the user's explicit permission, without constantly sharing credentials.

Instead of sending username and password in each requestOAuth 2.0 introduces the concept of an access token: a short-lived access token that is sent in HTTP calls to the API and validated by the API. The IdP (Keycloak, for example) issues this token after verifying the user's identity and consent.

The standard defines several authorization flows (grant types) to adapt the process to the type of client: secure backend applications, browser-based SPAs, apps mobile devices, limited devices, machine-to-machine communications, etc. Each flow marks what is exchanged at each step (authorization codes, tokens, credentials, etc.).

The four fundamental roles of OAuth 2.0 are:

• Resource Owner: usually the user whose data you want to consult or modify.
• Client: the application (web, mobile, IoT, backend…) that wants to act on behalf of the user.
• resource server: the API that exposes the data and validates the access tokens.
• Authorization Server: the IdP (Keycloak) that authenticates the user and issues tokens.

In addition, OAuth 2.0 introduces the concept of scopesThese define the scope of the permission the user grants to the application: reading email, posting on a social network, accessing a basic profile, etc. The issued token encodes which permissions have actually been granted to the client.

OpenID Connect: an identity layer on top of OAuth 2.0

OpenID Connect (OIDC) adds identity to OAuth 2.0While OAuth deals with authorization (what an application can do), OIDC deals with identifying in a standardized way who the authenticated user is and how to obtain their basic data.

OIDC defines well-known endpoints and metadata, such as the discovery document published on the route /.well-known/openid-configuration where the provider specifies authorization URLs, token, public keys, user info, etc. This allows applications to be configured almost automatically.

It also provides the UserInfo endpoint.This is used to retrieve information from the authenticated user (name, email, etc.) using a valid access token. It is very common in Keycloak-based integrations to read this data after login to populate user profiles in the application.

Access_token and JSON Web Tokens (JWT)

In many modern implementations, the access_token is a JWT (JSON Web Token). This is a standard (RFC 7519) for representing claims as a digitally signed JSON, in three parts separated by periods: header, payload, and signature, all encoded in Base64URL.

The header indicates technical information about the token. (signature algorithm, token type, and often the identifier of the key used, kidThe payload contains the claims, such as:

• exp: expiration date.
• see below: time of broadcast.
• iss: issuer, usually the IdP URL.
• under: unique user identifier.
• aud: audience to which the token is directed.
• JTI: unique identifier of the token.

The signature is generated with a private or secret key.Therefore, any modification to the token breaks the signature and is detected during validation. The API obtains the public key from the IdP thanks to the property jwks_uri from the discovery document, which points to a JSON file containing the list of public keys and their kid.

Keycloak also allows customization of the issued tokensAdditional claims can be added based on user attributes, groups, roles, or even fixed values. This is done using mappers configured per client or per client scope, making it easy for APIs to receive exactly the information they need.

Keycloak Architecture: Realms, Users, Groups, and Roles

Keycloak organizes its configuration in RealmsThese are like “virtual identity servers” within a single installation. Other vendors call something similar a tenant or directory. Each realm has its own independent users, groups, clients, policies, and settings.

By default there is a special realm called masterThis account should be reserved for global administrative tasks, such as creating and managing other realms. The administrator user can manage multiple realms from the same console without having to log in with different accounts for each one.

Local users can be defined within a realmassigning them custom attributes, grouping them, and relating them to roles. The model is carefully designed so that relevant information is ultimately reflected in the tokens consumed by the application (roles, groups, profile data, security flags, etc.).

Groups allow users to be organized hierarchically.A group can have subgroups (children), and a user inherits the attributes and roles of all the groups they belong to, including their parents. This allows for very flexible authorization models without having to repeat configurations for each user.

In terms of roles, there are two main levels:

• Realm roles: globals within the realm, used a lot for cross-property permissions.
• Client roles: specific to a particular application, allowing fine granularity for each service.

Keycloak supports composite rolesThat is, roles that in turn include other roles. This helps to group permissions and assign them all at once to users or groups, although it's best not to overuse it to avoid complicating management or affecting performance.

Installing Keycloak in development mode: Docker, Kubernetes, and VM

To set up a lab environment with Keycloak There are several simple options: Docker container, deployment on Kubernetes (for example with Minikube) or classic installation on a virtual machine with Linux and OpenJDK.

Keycloak in Docker

The fastest way to start Keycloak for testing It involves running a container with the official image, exposing port 8080 and passing the administrator username and password through environment variables, booting into mode start-dev (without HTTPS and with embedded H2 database):

With a single Docker command a functional server is obtained in http://localhost:8080, enough to tinker with the administration console, create realms, users, clients and test basic integrations.

Keycloak in Kubernetes with Minikube

If you already work with Kubernetes, you can easily deploy Keycloak. Using the sample manifests from the official repository, you create a Deployment and a Service, and then open a tunnel with Minikube to access the service from your machine, usually again on port 8080.

This approach is ideal for simulating environments closer to production. (with pods, services, external configuration, etc.) and to experiment with controlled deployments, scaling, and upgrades of Keycloak on K8s clusters.

Keycloak on Ubuntu with OpenJDK and PostgreSQL (advanced dev mode)

Another possibility is to install Keycloak on an Ubuntu VM Using OpenJDK and a local PostgreSQL database, with a self-signed certificate and custom hostname. Although still a test scenario, it's getting closer to a production topology.

Typical steps include:

• Update the operating system and install Java (for example, OpenJDK 11 or higher).
• Install PostgreSQL (ideally on a separate server, although in a lab it can be on the same machine).
• Create a specific user and database for Keycloak and grant the appropriate privileges.
• Create a system user without privileges (e.g. keycloak) to run the service.
• Download the official Keycloak distribution, unzip it into /opt/keycloak and adjust permissions.
• Generate a self-signed X.509 certificate with openssl and set it in keycloak.conf along with the PostgreSQL connection parameters and the hostname wanted.
• Define a unit systemd To start Keycloak in development mode at system startup, set administrator credentials via environment variables.

Once the service is up and runningIt is normally accessed via HTTPS on port 8443 with the configured hostname. If a self-signed certificate is used, it will need to be trusted in the browser (by importing the CA or the certificate itself into the machine's trusted certificate store).

Advanced deployments: high availability, PostgreSQL and reverse proxy

When we move from laboratory to productionThe picture changes: you have to think about high availability, robust data persistence, valid certificates and, often, a reverse proxy that centralizes HTTPS access and load balancing.

A fairly common pattern is to deploy multiple Keycloak nodes behind a load balancer (e.g., Nginx) and using a PostgreSQL database in HA mode as the persistence backend. The goal is to eliminate single points of failure for both the application and data layers.

In this type of architecture, steps such as the following are usually followed::

• Prepare updated Linux servers (Debian/Ubuntu) and install dependencies: unzip, wget, openjdk, openssl, etc.
• Create a system user keycloak with home in /opt/keycloak and without privileged interactive login permissions.
• Download the desired version of Keycloak, unzip it, and assign ownership to the dedicated user.
• Create a specific database in PostgreSQL, with the appropriate user and privileges, also adjusting the schema owner and default permissions on tables.
• Generate self-signed certificates (or use certificates from an internal CA) for Keycloak nodes and configure HTTPS on the application server.
• Adjust keycloak.conf to connect to the PostgreSQL VIP, define HTTP/HTTPS ports, certificates, proxy parameters, hostname, cluster stack (e.g., UDP), and log levels.
• Define a service systemd simple that Boot Keycloak with kc.sh start o kc.sh start --optimizedmanaging automatic restarts in case of failures.

Nginx is usually deployed on top of the publishing and load balancing layer. as an HTTPS reverse proxy, with its own TLS certificate and an upstream configuration that points to Keycloak nodes on its backend ports (usually 8080 if TLS is terminated in Nginx).

To eliminate single points of failure in the balancerIt is common to configure two Nginx nodes in high availability using Keepalived. This tool manages a floating virtual IP (VIP) that is advertised on one of the servers as the master and, in case of failure, switches to the backup node, maintaining service continuity.

Setting up a Realm, users, and application (client) registration

Once we have Keycloak up and running, the next logical step It involves creating a realm for our users and applications, and from there defining users, groups, roles and clients (the applications that will delegate authentication to Keycloak).

A new realm is created from the Admin Console. Simply by entering its name. From that moment on, we'll have an isolated space with its own settings. Among the first adjustments, the following are usually useful:

• Configure SMTP for sending emails (email verification, password recovery, notifications).
• Enable if desired Declarative User Profile, which allows you to declaratively define what attributes a user will have, what validations apply, and whether they are editable by the user.
• Adjust login parameters: allow or disallow self-registration, remember session between browser restarts, allow password recovery, etc.

Creating a user in a realm is as simple as filling out a form You'll need a username, email address, first and last name. Then, you set your password (temporary or permanent) from the credentials tab. From there, you can assign groups, roles, and additional attributes.

Keycloak offers a dedicated Account Console for end users.where they can view and modify their profile data, change their password, review active sessions, or manage additional authentication factors. It's a very convenient way to delegate some of the basic administration of their account to the user.

Impersonation is another interesting feature.An administrator with permission can "impersonate" a user from the console to reproduce problems, verify permissions, etc., without needing the user's password.

For an application to use Keycloak as an IdPIt must be registered as a client. In the Clients section, a new client ID is created, the type is indicated as OpenID Connect (unless SAML is to be used), and the allowed OAuth 2.0 flows are selected: Standard Flow (Authorization Code), Direct Access Grants (Password), Implicit, Client Credentials (service accounts), Device Code, CIBA, etc.

The client configuration also decides If client authentication (client secret or certificates) is required, which redirect URIs are valid and which web origins are allowed (very important in SPAs due to CORS policies). From there, the application can use official or third-party libraries to delegate authentication to Keycloak via OIDC.

Integration with external directories and other identity providers

Keycloak can function as a local identity source (users, groups and roles defined within its own database) or it can act as an identity broker to one or more external providers.

A very common integration is with Azure Active DirectoryAzure AD stores corporate users and groups, and Keycloak connects as an OIDC client to download identities and groups, mapping them to local users and roles. This avoids duplicating identities and administrative tasks across multiple sites.

In general terms, to use Azure AD as an external IdP the following is done:

• Register an application in Azure AD, obtaining its client ID and creating a client secret.
• Configure in Azure AD the redirect URIs to Keycloak (OIDC broker endpoint in the corresponding realm).
• Adjust the claims that will be issued in the token in the Azure AD application, for example by including the user groups.
• In Keycloak, create an OpenID Connect Identity Provider pointing to the Azure endpoints (authorization, token, logout, userinfo) and configuring client ID, client secret, and the desired login parameters.

Once trust has been established between themWhen a user signs in through Azure AD, Keycloak creates (or synchronizes) the user locally and can map Azure groups to Keycloak roles using advanced mappers. For example, the "Developers" group in Azure can be translated into the "Developers" role in Keycloak, which is then rolled out to integrated applications and services (such as Jenkins).

In addition to Azure AD, Keycloak allows identity federation with LDAP, classic Active Directory, other OIDC IdPs, social providers (Google, Facebook, GitHub, etc.) and more, being able to mix several sources simultaneously within the same realm.

Additional security: bots, CAPTCHA, and best practices

Although Keycloak greatly strengthens authentication security (MFA, password policies, account lockout, session control, etc.), login, registration and password recovery pages remain clear targets for bots and automated attacks.

To mitigate these types of threatsIt is recommended to combine Keycloak with anti-bot mechanisms such as GDPR-compliant CAPTCHA solutions that distinguish between human and automated traffic without compromising the user experience. These solutions are typically integrated into login and registration forms, adding an extra layer of defense against credential stuffing attacks, mass account creation, or abuse of password recovery flows.

Beyond CAPTCHA, other good practices include monitor logs for access, set up alerts for anomalous spikes in failed attempts, periodically review issued tokens and their duration, ensure that only necessary endpoints are exposed to the outside, and keep Keycloak and its dependencies updated with the latest security patches.

This entire ecosystem of functionalities (SSO, multi-tenancy, integration with external directories, configurable tokens, high availability deployments and bot protection) makes Keycloak a very powerful tool for centralizing authentication and authorization for modern applications, helping companies strengthen their security posture without sacrificing user experience or continually reinventing identity management.