Safa Bayar
About Blog Categories Contact
Safa Bayar

Contents

Keycloak Authentication Integration Demo

Safa Bayar included in Hobby Projects
   1217 words   6 minutes 

Keycloak Authentication Integration Demo

In this post, I’ll walk through my Keycloak Auth Demo project, which demonstrates how to integrate Keycloak for authentication and authorization in modern web applications.

Project Overview

The Keycloak Auth Demo showcases enterprise-grade authentication and authorization using Keycloak, an open-source identity and access management solution. This project demonstrates best practices for implementing secure authentication flows in web applications.

Why Keycloak?

Enterprise Features

  • Single Sign-On (SSO): Centralized authentication across multiple applications
  • Multi-Factor Authentication: Built-in MFA support
  • Identity Federation: Integration with external identity providers
  • Role-Based Access Control: Fine-grained authorization
  • Audit Logging: Comprehensive security audit trails

Developer Benefits

  • OAuth 2.0 & OpenID Connect: Industry-standard protocols
  • Multiple Client Types: Web, mobile, and API client support
  • Customizable UI: Branded login pages and user management
  • REST API: Programmatic management capabilities
  • Admin Console: User-friendly administration interface

Technical Architecture

Core Components

  • Keycloak Server: Identity and access management server
  • Client Application: Demo web application
  • Database: PostgreSQL for Keycloak data storage
  • Reverse Proxy: Nginx for SSL termination and load balancing

Authentication Flow

Implementation Details

Keycloak Configuration

Realm Setup

{
  "realm": "demo-realm",
  "enabled": true,
  "displayName": "Demo Authentication Realm",
  "loginWithEmailAllowed": true,
  "duplicateEmailsAllowed": false,
  "resetPasswordAllowed": true,
  "editUsernameAllowed": false,
  "bruteForceProtected": true,
  "permanentLockout": false,
  "maxFailureWaitSeconds": 900,
  "minimumQuickLoginWaitSeconds": 60,
  "waitIncrementSeconds": 60,
  "quickLoginCheckMilliSeconds": 1000,
  "maxDeltaTimeSeconds": 43200,
  "failureFactor": 30
}

Client Configuration

{
  "clientId": "demo-client",
  "name": "Demo Application",
  "description": "Demo application for Keycloak integration",
  "enabled": true,
  "clientAuthenticatorType": "client-secret",
  "secret": "demo-client-secret",
  "redirectUris": [
    "http://localhost:3000/*",
    "https://demo.example.com/*"
  ],
  "webOrigins": [
    "http://localhost:3000",
    "https://demo.example.com"
  ],
  "protocol": "openid-connect",
  "publicClient": false,
  "standardFlowEnabled": true,
  "implicitFlowEnabled": false,
  "directAccessGrantsEnabled": true,
  "serviceAccountsEnabled": true
}

Application Integration

Frontend Integration (JavaScript)

class KeycloakAuth {
  constructor() {
    this.keycloak = new Keycloak({
      url: 'http://localhost:8080/auth',
      realm: 'demo-realm',
      clientId: 'demo-client'
    });
  }

  async init() {
    try {
      const authenticated = await this.keycloak.init({
        onLoad: 'check-sso',
        silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html'
      });
      
      if (authenticated) {
        console.log('User authenticated');
        this.updateUI();
      } else {
        console.log('User not authenticated');
      }
    } catch (error) {
      console.error('Authentication failed:', error);
    }
  }

  login() {
    this.keycloak.login();
  }

  logout() {
    this.keycloak.logout();
  }

  getToken() {
    return this.keycloak.token;
  }

  updateUI() {
    const userInfo = this.keycloak.tokenParsed;
    document.getElementById('username').textContent = userInfo.preferred_username;
    document.getElementById('email').textContent = userInfo.email;
  }
}

// Initialize authentication
const auth = new KeycloakAuth();
auth.init();

Backend Integration (Node.js)

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

const app = express();

// Keycloak configuration
const keycloakConfig = {
  realm: 'demo-realm',
  'auth-server-url': 'http://localhost:8080/auth',
  'ssl-required': 'external',
  resource: 'demo-client',
  'confidential-port': 0,
  'client-secret': 'demo-client-secret'
};

// Initialize Keycloak
const keycloak = new Keycloak({}, keycloakConfig);

// Session configuration
app.use(session({
  secret: 'demo-session-secret',
  resave: false,
  saveUninitialized: true,
  store: new MemoryStore()
}));

// Keycloak middleware
app.use(keycloak.middleware());

// Protected routes
app.get('/protected', keycloak.protect(), (req, res) => {
  res.json({
    message: 'This is a protected resource',
    user: req.kauth.grant.access_token.content
  });
});

// Admin route (requires specific role)
app.get('/admin', keycloak.protect('admin'), (req, res) => {
  res.json({
    message: 'Admin access granted',
    user: req.kauth.grant.access_token.content
  });
});

Security Features Implemented

Authentication Security

  • Password Policies: Strong password requirements
  • Account Lockout: Protection against brute force attacks
  • Session Management: Secure session handling
  • Token Expiration: Configurable token lifetimes

Authorization Features

  • Role-Based Access: Fine-grained role management
  • Resource Permissions: Resource-level permissions
  • Scope-Based Access: OAuth 2.0 scope implementation
  • Policy Enforcement: Custom authorization policies

Advanced Security

  • Multi-Factor Authentication: TOTP and SMS support
  • Social Login: Integration with Google, GitHub, etc.
  • Identity Federation: SAML and OIDC federation
  • Audit Logging: Comprehensive security audit trails

User Management

User Registration Flow

// Custom user registration
const registerUser = async (userData) => {
  try {
    const response = await fetch('/auth/admin/realms/demo-realm/users', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${adminToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        username: userData.username,
        email: userData.email,
        firstName: userData.firstName,
        lastName: userData.lastName,
        enabled: true,
        credentials: [{
          type: 'password',
          value: userData.password,
          temporary: false
        }]
      })
    });
    
    return response.ok;
  } catch (error) {
    console.error('Registration failed:', error);
    return false;
  }
};

Role Management

// Assign roles to users
const assignRole = async (userId, roleName) => {
  try {
    const role = await getRoleByName(roleName);
    const response = await fetch(
      `/auth/admin/realms/demo-realm/users/${userId}/role-mappings/realm`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${adminToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify([role])
      }
    );
    
    return response.ok;
  } catch (error) {
    console.error('Role assignment failed:', error);
    return false;
  }
};

Deployment Configuration

Docker Compose Setup

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    command: start-dev

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
    volumes:
      - postgres_data:/var/lib/postgresql/data

  demo-app:
    build: .
    ports:
      - "3000:3000"
    environment:
      KEYCLOAK_URL: http://keycloak:8080/auth
      KEYCLOAK_REALM: demo-realm
      KEYCLOAK_CLIENT_ID: demo-client
      KEYCLOAK_CLIENT_SECRET: demo-client-secret
    depends_on:
      - keycloak

volumes:
  postgres_data:

Production Configuration

# Keycloak production configuration
export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=secure-password
export KC_DB=postgres
export KC_DB_URL=jdbc:postgresql://prod-db:5432/keycloak
export KC_DB_USERNAME=keycloak
export KC_DB_PASSWORD=secure-db-password
export KC_HOSTNAME=keycloak.example.com
export KC_HOSTNAME_PORT=443
export KC_HOSTNAME_STRICT_HTTPS=true
export KC_HTTP_ENABLED=false
export KC_PROXY=edge

Testing Strategy

Unit Tests

describe('KeycloakAuth', () => {
  let auth;
  
  beforeEach(() => {
    auth = new KeycloakAuth();
  });
  
  test('should initialize successfully', async () => {
    const mockKeycloak = {
      init: jest.fn().mockResolvedValue(true),
      tokenParsed: { preferred_username: 'testuser' }
    };
    
    auth.keycloak = mockKeycloak;
    await auth.init();
    
    expect(mockKeycloak.init).toHaveBeenCalled();
  });
  
  test('should handle authentication failure', async () => {
    const mockKeycloak = {
      init: jest.fn().mockRejectedValue(new Error('Auth failed'))
    };
    
    auth.keycloak = mockKeycloak;
    
    await expect(auth.init()).rejects.toThrow('Auth failed');
  });
});

Integration Tests

describe('Protected Routes', () => {
  test('should allow access with valid token', async () => {
    const token = await getValidToken();
    
    const response = await request(app)
      .get('/protected')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);
    
    expect(response.body.message).toBe('This is a protected resource');
  });
  
  test('should deny access without token', async () => {
    await request(app)
      .get('/protected')
      .expect(401);
  });
});

Performance Optimization

Caching Strategy

  • Token Caching: Cache access tokens to reduce authentication requests
  • User Info Caching: Cache user information for improved performance
  • Role Caching: Cache user roles to reduce authorization checks

Database Optimization

  • Connection Pooling: Efficient database connection management
  • Query Optimization: Optimized queries for user and role lookups
  • Indexing: Proper database indexing for performance

Monitoring and Logging

Audit Logging

// Custom audit logging
const auditLog = (event, userId, details) => {
  console.log(JSON.stringify({
    timestamp: new Date().toISOString(),
    event: event,
    userId: userId,
    details: details,
    source: 'demo-application'
  }));
};

// Usage in authentication flow
auditLog('LOGIN_SUCCESS', user.id, {
  ip: req.ip,
  userAgent: req.headers['user-agent']
});

Health Checks

// Keycloak health check
const checkKeycloakHealth = async () => {
  try {
    const response = await fetch(`${keycloakUrl}/health`);
    return response.ok;
  } catch (error) {
    return false;
  }
};

Lessons Learned

Security Best Practices

  • Token Management: Proper token storage and handling
  • Session Security: Secure session configuration
  • Input Validation: Validate all user inputs
  • Error Handling: Don’t expose sensitive information in errors

Integration Challenges

  • CORS Configuration: Proper CORS setup for cross-origin requests
  • Token Refresh: Implement automatic token refresh
  • Error Handling: Graceful handling of authentication failures
  • User Experience: Smooth authentication flow for users

Future Enhancements

Advanced Features

  • Biometric Authentication: Fingerprint and face recognition
  • Risk-Based Authentication: Adaptive authentication based on risk
  • API Gateway Integration: Integration with API gateways
  • Mobile SDK: Native mobile application support

Scalability Improvements

  • Clustering: Keycloak cluster setup for high availability
  • Load Balancing: Load balancer configuration
  • Caching: Redis integration for improved performance
  • Monitoring: Comprehensive monitoring and alerting

Conclusion

The Keycloak Auth Demo project demonstrates the power of modern identity and access management. Key achievements include:

  • Enterprise Security: Implementation of enterprise-grade authentication
  • Standards Compliance: OAuth 2.0 and OpenID Connect compliance
  • Developer Experience: Easy integration with existing applications
  • Scalability: Production-ready configuration and deployment
  • Security: Comprehensive security features and best practices

The project is available on GitHub and serves as a comprehensive reference for Keycloak integration.

This project represents my exploration into enterprise identity management and showcases how modern authentication systems can be integrated into web applications. The lessons learned here continue to influence my approach to application security and user management.

Updated on 2025-02-10
 , , , , , 
Back | Home