An Introduction to Keycloak: Simplifying Authentication & Identity Management

In today’s world, security is not optional. Whether you're building a small web app or architecting a multi-tenant, enterprise-scale system, handling authentication and authorization is critical.

But here’s the challenge:

• Managing user logins across multiple apps is a hassle.
• Handling OAuth2, OpenID Connect, and SAML manually is a pain.
• Ensuring Single Sign-On (SSO), Role-Based Access Control (RBAC), and Multi-Factor Authentication (MFA) can get complicated fast.

Enter Keycloak, an open-source Identity and Access Management (IAM) solution that makes authentication easier, scalable, free, and secure.

What is Keycloak?

Keycloak is a powerful tool that provides:

1. Single Sign-On (SSO) – Users log in once and access multiple apps.
2. OAuth2, OpenID Connect, and SAML Support – Standard authentication protocols built-in.
3. Role-Based Access Control (RBAC) – Assign different roles to users.
4. Multi-Factor Authentication (MFA) – Extra security with OTPs, WebAuthn, and more.
5. Social & Enterprise Login Integration – Login via Google, GitHub, Azure AD, etc.
6. API Security – Protect APIs with OAuth2 token-based authentication.

It removes the need for developers to build authentication from scratch, allowing them to focus on business logic instead.

So, how does Keycloak work?

At its core, Keycloak acts as an identity broker between users and applications.

Key Concepts to know:

• Realm: A logical container for users, roles, and applications. You can create separate realms for different organizations or tenants.
• Clients: Applications that use Keycloak for authentication (e.g., web apps, APIs).
• Identity Providers (IdP): External authentication sources like Google, GitHub, or Active Directory.
• Users & Roles: Define who can access what. Users are assigned roles that grant them specific permissions.
• Tokens: Keycloak issues JWT tokens to authenticate and authorize users.

How Authentication Works in Keycloak

1. User visits an app AKA (Client)
2. The app redirects them to Keycloak login page (This could be customized)
3. User logs in (Keycloak validates credentials)
4. Keycloak issues a token (JWT) back to the app
5. App uses this token to grant access

This is secure, scalable, and eliminates the need for storing passwords in apps.

Alright, this is cool and all buttt... I bet it's complicated to work with? Not really(ish).

Step 1: Running Keycloak Locally

To spin up Keycloak on your machine using Docker, run:

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

Now, open http://localhost:8080 and log in with: Username: admin Password: admin

Step 2: Setting Up a Client (Your App)

Now, let’s connect an application to Keycloak.

1. Go to Keycloak Admin Panel → Clients
2. Click "Create Client"
3. Set:

• Client ID: my-web-app
• Protocol: openid-connect
• Root URL: http://localhost:3000 (or whatever you root url is)
• Save & Configure Access Settings

This registers your application so it can use Keycloak for authentication.

Step 3: Integrating Keycloak in a Web App

Using Keycloak in a Node.js API (Backend)

Install the required package:

1. npm install keycloak-connect express

2. Then, add Keycloak middleware to your Express app:

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

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

const keycloak = new Keycloak({ store: memoryStore });

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

app.use(keycloak.middleware());

// Protect an API route
app.get('/protected', keycloak.protect(), (req, res) => {
  res.json({ message: "You're authenticated!", user: req.kauth.grant.access_token.content });
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));
        

Now, visiting /protected will require authentication via Keycloak.

Using Keycloak in a React App (Frontend)

First, install Keycloak's JavaScript SDK:

npm install keycloak-js        

Then, initialize Keycloak in your React app:

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
  url: 'http://localhost:8080',
  realm: 'myrealm',
  clientId: 'my-web-app'
});

keycloak.init({ onLoad: 'login-required' })
  .then(authenticated => {
    console.log(authenticated ? 'Authenticated' : 'Not authenticated');
  });
        

This redirects users to Keycloak login, then back to your app.

With Keycloak, you don’t have to worry about managing passwords, securing APIs, or implementing complex login flows, it’s all handled for you.

The real challenge is how you handle things within the Realms, thats a topic for next week!

Share your thoughts below, please!