Building an Identity and Access Management System with Keycloak: A Practical Guide

As Users, we all have experienced the convenience of clicking “Sign in with Google” or “Continue with GitHub” instead of filling out lengthy registration forms. But have you ever wondered what powers these seamless authentication experiences? In this lab, I’ll walk you through my hands-on project implementing OpenID Connect using Keycloak, an open-source identity and access management solution.

Understanding OAuth 2.0 and OpenID Connect

Before diving into the implementation, lets understand some of these fundamental concepts:

OAuth 2.0 is an authorization framework that allows users to grant third-party applications access to their resources without sharing passwords. You encounter OAuth every day when Zoom asks permission to access your calendar, when your school portal requests access to your exam dashboard, or when you authorize apps to post on your behalf.

OpenID Connect builds on OAuth 2.0 to handle authentication. While OAuth handles authorization (“Can this app access my data?”), OpenID Connect handles authentication (“Who is this user?”). When you click “Sign in with Google,” OpenID Connect creates an ID token, establishes your account, and authenticates you — all in one smooth flow.

Why Keycloak?

After years of using social login features as an end-user, I wanted to understand how to build these systems myself. Keycloak proved to be the perfect learning platform because it’s:

• Open-source and production-ready
• Supports OAuth 2.0 and OpenID Connect out of the box
• Highly configurable with enterprise-grade security features
• Easy to integrate with existing applications

My POC on identity and access management using keycloak

I runed keycloak on my docker

//the Code to pull docker images version 23.0.6
docker pull quay.io/keycloak/keycloak:23.0.6

//login using on the start-dev
docker run -d -p 8080:8080 \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=your-password \
    -e KC_PROXY=edge \
    --restart always \
    -v /your/projet/path:/opt/jboss/keycloak/standalone/data \
    quay.io/keycloak/keycloak:23.0.6 start-dev

Production Setup (Persistent with PostgreSQL)

For a production-grade setup, I configured Keycloak with PostgreSQL for data persistence, data are safe after restart:

Production Setup (Persistent with PostgreSQL)
For a production-grade setup, I configured Keycloak with PostgreSQL for data persistence:version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    container_name: keycloak
    command: start --optimized
    environment:
      KC_DB: postgres
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: mysecretpassword
      KC_DB_URL_HOST: keycloak-db
      KC_DB_URL_DATABASE: keycloak
      KC_HTTP_PORT: 8080
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    volumes:
      - ./keycloak/keycloak.conf:/opt/keycloak/conf/keycloak.conf
      - keycloak_data:/opt/keycloak/data
    depends_on:
      - keycloak-db
    restart: always

  keycloak-db:
    image: postgres:16
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: always

volumes:
  postgres_data:
  keycloak_data:

After setting up our keycloak we need to create an admin user as the one created is a tempora admin an should be used in producition , we login using the default admin admin credentials you ill notice a badge showing this warning, so create a new user assing admin privilages and delete the temporay admin user followin the best secuirty practice

You are logged in as a temporary admin user. To harden security, create a permanent admin account and delete the temporary one.

Also create a realme, using like you shoul’dt push to your github master branch or you wont be wearing you expensive wrist watch on a normal event you should not be using your master realme,

As you can see in the image my current reame is “my-server” all my setup and production goes under here.

Setting up my client

A client is like an application, setting up my application on keycloak followin this steps

keycloak client setup

I attached a consent form where user will be asked if to alllow access to ther email, profile etc. Also set up Client authentication since am building a private and not a public, my backend performs my commication with the the keycloack for authentication, I also attached my redirect url the url that will be redirected to affter authentication might have taken place, proper condiguration of the url is required to avoid redirecting the users to malicious sites. https://learn.snyk.io/lesson/open-redirect/.

Users creation

users are entites that are with the system that need to perform an action, here we use humans as there are what we authenticate and give access so the can have access to other applications, assign the neccesary action you want to user to perform, like confirm their email, setup otp, update primary set password and lot more.

Let go configure more action to secure our user like password policy, otp policy, and lot more.

so we setup authentication policies like the password minimum length, charaters, digits number of passowrd reuse so as to avoid passowrd reuse settup password rotation, also settting up the has algorithim flow

Authentication policy and lot more

Nomally for you to enter a house, lets say a fence house, you passwd from the gate then to the door, the you can have access juat a breif anology. so we setup a flow a browser flow were a user will be prompted to setup a MFA kinda two factor authentication flow using either google authenticator, freeapp to generate an OTP which is a one time password which will be required anytime a user is trying to login into an application

Keycloak’s official documentation provides this important warning about 2FA setup:

“Make sure to properly test your configuration when you configure the authentication flow to confirm that no security holes exist in your setup. We recommend that you test various corner cases. For example, consider testing the authentication behavior for a user when you remove various credentials from the user’s account before authentication.”

Important Edge Case: When second-factor authenticators (like OTP or WebAuthn) are set as REQUIRED but the user doesn’t have that credential type, they can set it up during authentication itself. This means they don’t actually authenticate with it on first use. Always configure a reliable first-factor credential like Password or WebAuthn Passwordless Authenticator for browser authentication.

Testing our Flow

I used the the php code setup from https://www.oauth.com/oauth2-servers/accessing-data/setting-up-the-environment/.

php code flow on localhost

This above shows a user who tries to login , after entering basic password and user-name then been prompted to setup 2FA thereby enforcing defence indepth a core part of cyber security.

Architecture Overview

The complete system architecture includes:

• Keycloak Server: Running in Docker with PostgreSQL backend
• Authentication Flow: Browser-based with MFA support
• Client Application: Configured with proper redirect URIs and consent screens
• User Management: Complete lifecycle management with security policies
• Database: PostgreSQL for persistent data storage

Building this IAM system from scratch demystified the “Sign in with…” buttons we use daily. Keycloak proved to be a robust, production-ready solution that handles the complexity of modern authentication while remaining developer-friendly.

IAM #CyberSecurity #CloudSecurity #OpenLDAP #IdentityManagement #DevSecOps