Said Olano

Posted on Aug 22

Keycloak: Open Source Identity and Access Management (2026-08-22 18:35)

#keycloak #security #authentication #oauth2

Keycloak: Identity and Access Management

Managing user authentication and authorization across multiple applications is one of the most repetitive and error-prone tasks in modern software development. Rather than building login flows, password storage, and token management from scratch for every project, teams can delegate these responsibilities to a dedicated identity provider. Keycloak is one of the most popular open source solutions in this space.

What Is Keycloak?

Keycloak is an open source Identity and Access Management (IAM) tool originally developed by Red Hat and now part of the Cloud Native Computing Foundation (CNCF). It provides authentication and authorization services so that developers can secure applications and services with minimal effort.

Key capabilities include:

Single Sign-On (SSO) across web and mobile applications
Identity Brokering with social login providers (Google, GitHub, etc.)
User Federation with LDAP and Active Directory
Standard protocol support: OpenID Connect, OAuth 2.0, and SAML 2.0
Fine-grained authorization using roles, groups, and policies

Core Concepts

Understanding a few fundamental terms is essential before working with Keycloak.

Realms

A realm is an isolated space where you manage users, credentials, roles, and clients. Objects in one realm are completely separated from another. The master realm is created by default and should be used only for administration.

Clients

A client represents an application that wants to use Keycloak for authentication. Each client has its own configuration, including redirect URIs and access type (public, confidential, or bearer-only).

Users, Roles, and Groups

Users are individuals who authenticate against a realm.
Roles define permissions and can be realm-level or client-level.
Groups allow you to organize users and assign roles collectively.

Getting Started with Docker

The fastest way to try Keycloak is by running it in a container.

docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Once running, navigate to http://localhost:8080 and log in to the admin console using the credentials above.

Configuring a Realm and Client

After logging in:

Create a new realm (e.g., demo).
Register a client (e.g., my-app) with the OpenID Connect protocol.
Set a valid redirect URI, such as http://localhost:3000/*.
Create a test user under the Users section and set a password.

Integrating with an Application

Keycloak works with any OpenID Connect compliant library. Below is a minimal example using Node.js and the keycloak-connect adapter.

const session = require('express-session');
const Keycloak = require('keycloak-connect');
const express = require('express');

const app = express();
const memoryStore = new session.MemoryStore();

app.use(session({
  secret: 'a-strong-secret',
  resave: false,
  saveUninitialized: true,
  store: memoryStore
}));

const keycloak = new Keycloak({ store: memoryStore });
app.use(keycloak.middleware());

// Protect a route
app.get('/secure', keycloak.protect(), (req, res) => {
  res.json({ message: 'You accessed a protected resource!' });
});

app.listen(3000, () => console.log('App running on port 3000'));

The corresponding keycloak.json configuration:

{
  "realm": "demo",
  "auth-server-url": "http://localhost:8080/",
  "ssl-required": "external",
  "resource": "my-app",
  "public-client": true,
  "confidential-port": 0
}

Understanding the Token Flow

When a user authenticates, Keycloak issues three tokens:

Token	Purpose
Access Token	A short-lived JWT used to authorize API requests
ID Token	Contains user identity claims (OpenID Connect)
Refresh Token	Used to obtain new access tokens without re-authentication

A typical Authorization Code flow proceeds as follows:

The user is redirected to Keycloak's login page.
After successful login, Keycloak returns an authorization code.
The application exchanges the code for tokens.
The access token is included in the Authorization: Bearer header for API calls.

Securing APIs with Bearer Tokens

Backend services can validate incoming JWTs without contacting Keycloak on every request by verifying the token signature against the realm's public key.

curl -H "Authorization: Bearer <access_token>" \
  http://localhost:3000/secure

The resource server checks the token's signature, expiration, issuer, and audience before granting access.

Best Practices

Use confidential clients for server-side applications and keep client secrets secure.
Enforce short token lifespans and rely on refresh tokens.
Enable brute-force detection in realm settings to protect against credential stuffing.
Do not use the master realm for your applications.
Externalize the database (PostgreSQL, MySQL) in production instead of the embedded store.
Run behind HTTPS and configure the ssl-required setting appropriately.

Conclusion

Keycloak removes the burden of building and maintaining authentication infrastructure by providing a robust, standards-based IAM platform out of the box. With support for SSO, social login, and fine-grained authorization, it scales from small projects to enterprise deployments. By centralizing identity management, teams can focus on building features while relying on a battle-tested security foundation.

To go further, expl

DEV Community