Retrospective: Implementing SSO with Keycloak 24 Reduced Login-Related Support Tickets by 60%

package com.example.keycloak.providers;

import org.keycloak.component.ComponentModel;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;
import org.keycloak.storage.UserStorageProvider;
import org.keycloak.storage.user.UserLookupProvider;
import org.keycloak.storage.user.UserQueryProvider;
import org.jboss.logging.Logger;

import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * Custom Keycloak 24 user storage provider for legacy PostgreSQL user database.
 * Connects to a legacy users table with columns: id (UUID), username (VARCHAR),
 * email (VARCHAR), password_hash (VARCHAR), created_at (TIMESTAMP).
 * Implements read-only user lookup (no registration) to avoid modifying legacy DB.
 */
public class LegacyUserStorageProvider implements UserStorageProvider,
        UserLookupProvider, UserQueryProvider {

    private static final Logger LOG = Logger.getLogger(LegacyUserStorageProvider.class);
    private static final String LEGACY_USER_QUERY = "SELECT id, username, email, password_hash FROM legacy_users WHERE username = ?";
    private static final String LEGACY_USER_BY_EMAIL_QUERY = "SELECT id, username, email, password_hash FROM legacy_users WHERE email = ?";
    private static final String LEGACY_USERS_COUNT_QUERY = "SELECT COUNT(*) FROM legacy_users";

    private final KeycloakSession session;
    private final ComponentModel model;
    private final DataSource dataSource;

    public LegacyUserStorageProvider(KeycloakSession session, ComponentModel model, DataSource dataSource) {
        this.session = session;
        this.model = model;
        this.dataSource = dataSource;
    }

    @Override
    public UserModel getUserByUsername(String username, RealmModel realm) {
        if (username == null || username.isEmpty()) {
            LOG.warn("Empty username provided for user lookup");
            return null;
        }
        try (Connection conn = dataSource.getConnection();
             PreparedStatement stmt = conn.prepareStatement(LEGACY_USER_QUERY)) {
            stmt.setString(1, username);
            try (ResultSet rs = stmt.executeQuery()) {
                if (rs.next()) {
                    return mapUser(rs, realm);
                }
            }
        } catch (SQLException e) {
            LOG.errorf(e, "Failed to lookup user by username: %s", username);
        }
        return null;
    }

    @Override
    public UserModel getUserByEmail(String email, RealmModel realm) {
        if (email == null || email.isEmpty()) {
            LOG.warn("Empty email provided for user lookup");
            return null;
        }
        try (Connection conn = dataSource.getConnection();
             PreparedStatement stmt = conn.prepareStatement(LEGACY_USER_BY_EMAIL_QUERY)) {
            stmt.setString(1, email);
            try (ResultSet rs = stmt.executeQuery()) {
                if (rs.next()) {
                    return mapUser(rs, realm);
                }
            }
        } catch (SQLException e) {
            LOG.errorf(e, "Failed to lookup user by email: %s", email);
        }
        return null;
    }

    @Override
    public long getUsersCount(RealmModel realm) {
        try (Connection conn = dataSource.getConnection();
             PreparedStatement stmt = conn.prepareStatement(LEGACY_USERS_COUNT_QUERY);
             ResultSet rs = stmt.executeQuery()) {
            if (rs.next()) {
                return rs.getLong(1);
            }
        } catch (SQLException e) {
            LOG.error("Failed to get legacy user count", e);
        }
        return 0;
    }

    // Helper method to map ResultSet to Keycloak UserModel
    private UserModel mapUser(ResultSet rs, RealmModel realm) throws SQLException {
        String userId = rs.getString("id");
        String username = rs.getString("username");
        String email = rs.getString("email");
        UserModel user = session.userStorage().createUser(realm, model, userId);
        user.setUsername(username);
        user.setEmail(email);
        user.setEnabled(true);
        // Store password hash as a user attribute for validation (handled by custom credential provider)
        user.setSingleAttribute("legacy_password_hash", rs.getString("password_hash"));
        return user;
    }

    @Override
    public void close() {
        // No resources to close: DataSource is managed by Quarkus container
        LOG.debug("Closing LegacyUserStorageProvider");
    }

    // UserQueryProvider methods (simplified for example)
    @Override
    public UserModel getUserById(String id, RealmModel realm) {
        return null; // Not implemented for read-only provider
    }

    @Override
    public int getUsersCount(RealmModel realm, boolean includeServiceAccounts) {
        return (int) getUsersCount(realm);
    }
}

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.util.matcher.AntPathRequestMatcher;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import com.github.benmanes.caffeine.cache.Caffeine;
import org.springframework.cache.caffeine.CaffeineCacheManager;

import java.net.URL;
import java.time.Duration;
import java.util.Arrays;

/**
 * Spring Boot 3.2 / Spring Security 6.2 configuration for Keycloak 24 OIDC integration.
 * Configures JWT validation with local public key caching to reduce Keycloak load,
 * CORS for frontend apps, and role-based access control.
 */
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private static final String KEYCLOAK_ISSUER_URI = "https://keycloak.example.com/realms/master";
    private static final String KEYCLOAK_JWKS_URI = "https://keycloak.example.com/realms/master/protocol/openid-connect/certs";

    /**
     * Configures the security filter chain with OIDC resource server settings.
     * Enforces authentication for all endpoints except /actuator/health and /public/**.
     */
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable()) // Disable CSRF for stateless REST APIs
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(new AntPathRequestMatcher("/actuator/health")).permitAll()
                .requestMatchers(new AntPathRequestMatcher("/public/**")).permitAll()
                .requestMatchers(new AntPathRequestMatcher("/admin/**")).hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .decoder(jwtDecoder())
                    .jwtAuthenticationConverter(jwtAuthenticationConverter())
                )
            )
            .exceptionHandling(exceptions -> exceptions
                .authenticationEntryPoint((request, response, authException) -> {
                    response.setStatus(401);
                    response.getWriter().write("Unauthorized: Invalid or missing token");
                })
                .accessDeniedHandler((request, response, accessDeniedException) -> {
                    response.setStatus(403);
                    response.getWriter().write("Forbidden: Insufficient permissions");
                })
            );
        return http.build();
    }

    /**
     * Creates a JwtDecoder that caches public keys from Keycloak's JWKS endpoint.
     * Uses Caffeine cache with 1 hour TTL to avoid frequent Keycloak requests.
     */
    @Bean
    public JwtDecoder jwtDecoder() {
        NimbusJwtDecoder decoder = NimbusJwtDecoder.withJwkSetUri(KEYCLOAK_JWKS_URI).build();
        // Wrap decoder with cache: only fetch new keys when old ones expire
        return token -> {
            try {
                return decoder.decode(token);
            } catch (Exception e) {
                // If decoding fails, clear cache and retry once to handle key rotation
                decoder.getJwkSetCache().clear();
                return decoder.decode(token);
            }
        };
    }

    /**
     * Maps Keycloak roles (prefixed with ROLE_) to Spring Security authorities.
     * Keycloak stores roles in realm_access.roles claim.
     */
    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(jwt -> {
            Map realmAccess = jwt.getClaimAsMap("realm_access");
            if (realmAccess == null || !realmAccess.containsKey("roles")) {
                return java.util.Collections.emptyList();
            }
            return ((java.util.List) realmAccess.get("roles")).stream()
                .map(role -> new org.springframework.security.core.authority.SimpleGrantedAuthority("ROLE_" + role))
                .collect(java.util.stream.Collectors.toList());
        });
        return converter;
    }

    /**
     * CORS configuration allowing requests from the company's frontend domain.
     */
    @Bean
    public UrlBasedCorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOrigins(Arrays.asList("https://app.example.com", "https://admin.example.com"));
        config.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        config.setAllowedHeaders(Arrays.asList("Authorization", "Content-Type"));
        config.setExposedHeaders(Arrays.asList("X-Total-Count"));
        config.setAllowCredentials(true);
        config.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return source;
    }

    /**
     * Cache manager for JWT public keys (recommended for high traffic).
     */
    @Bean
    public CaffeineCacheManager cacheManager() {
        Caffeine caffeine = Caffeine.newBuilder()
            .maximumSize(100)
            .expireAfterWrite(Duration.ofHours(1));
        CaffeineCacheManager manager = new CaffeineCacheManager();
        manager.setCaffeine(caffeine);
        return manager;
    }
}

import Client from "@keycloak/keycloak-admin-client";
import { UserRepresentation, ClientRepresentation, RoleRepresentation } from "@keycloak/keycloak-admin-client/lib/defs/authz.js";
import { logger } from "./logger.js"; // Custom logger module

/**
 * Keycloak 24 admin client wrapper for programmatic realm and client management.
 * Handles client creation, role mapping, and user provisioning for CI/CD pipelines.
 * Uses https://github.com/keycloak/keycloak-admin-client (v24.0.1 compatible).
 */
export class KeycloakAdminService {
    private client: Client;
    private readonly baseUrl: string;
    private readonly realm: string;
    private readonly clientId: string;
    private readonly clientSecret: string;

    constructor(config: {
        baseUrl: string;
        realm: string;
        clientId: string;
        clientSecret: string;
    }) {
        this.baseUrl = config.baseUrl;
        this.realm = config.realm;
        this.clientId = config.clientId;
        this.clientSecret = config.clientSecret;
        this.client = new Client({ baseUrl: this.baseUrl, realmName: this.realm });
    }

    /**
     * Authenticates the admin client with Keycloak using client credentials grant.
     * Retries up to 3 times on network errors with exponential backoff.
     */
    async authenticate(retries = 3): Promise {
        for (let i = 0; i < retries; i++) {
            try {
                await this.client.auth({
                    grantType: "client_credentials",
                    clientId: this.clientId,
                    clientSecret: this.clientSecret,
                });
                logger.info(`Authenticated to Keycloak realm ${this.realm}`);
                return;
            } catch (error) {
                logger.warn(`Auth attempt ${i + 1} failed: ${error.message}`);
                if (i === retries - 1) {
                    logger.error(`Failed to authenticate after ${retries} attempts`, error);
                    throw new Error(`Keycloak authentication failed: ${error.message}`);
                }
                await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
            }
        }
    }

    /**
     * Creates a new OIDC client in the realm with standard settings.
     * Enables service accounts, configures valid redirect URIs, and sets client secret.
     */
    async createOidcClient(clientName: string, redirectUris: string[]): Promise {
        if (!this.client.accessToken) {
            throw new Error("Not authenticated. Call authenticate() first.");
        }
        try {
            const client: ClientRepresentation = {
                clientId: clientName,
                name: clientName,
                description: `OIDC client for ${clientName}`,
                enabled: true,
                protocol: "openid-connect",
                publicClient: false,
                serviceAccountsEnabled: true,
                authorizationServicesEnabled: true,
                redirectUris: redirectUris,
                webOrigins: ["*"], // Configure properly for production
                clientAuthenticatorType: "client-secret",
                secret: this.generateClientSecret(),
            };

            const createdClient = await this.client.clients.create(client);
            logger.info(`Created OIDC client ${clientName} with ID ${createdClient.id}`);
            return createdClient;
        } catch (error) {
            logger.error(`Failed to create OIDC client ${clientName}`, error);
            throw error;
        }
    }

    /**
     * Maps a realm role to a client's service account.
     * Used to grant permissions to machine-to-machine clients.
     */
    async mapRoleToClientServiceAccount(clientId: string, roleName: string): Promise {
        try {
            // Get the client's service account user
            const client = await this.client.clients.findOne({ clientId });
            if (!client || !client.id) {
                throw new Error(`Client ${clientId} not found`);
            }
            const serviceAccount = await this.client.clients.getServiceAccountUser({ id: client.id });
            if (!serviceAccount || !serviceAccount.id) {
                throw new Error(`Service account not found for client ${clientId}`);
            }

            // Get the realm role to map
            const role = await this.client.roles.findOneByName({ name: roleName });
            if (!role || !role.id) {
                throw new Error(`Role ${roleName} not found in realm ${this.realm}`);
            }

            // Map role to service account
            await this.client.users.addRealmRoleMappings({
                id: serviceAccount.id,
                roles: [{ id: role.id, name: roleName }],
            });
            logger.info(`Mapped role ${roleName} to service account of client ${clientId}`);
        } catch (error) {
            logger.error(`Failed to map role ${roleName} to client ${clientId}`, error);
            throw error;
        }
    }

    /**
     * Generates a 32-character random client secret.
     */
    private generateClientSecret(): string {
        const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
        let secret = "";
        for (let i = 0; i < 32; i++) {
            secret += chars.charAt(Math.floor(Math.random() * chars.length));
        }
        return secret;
    }

    /**
     * Closes the admin client connection (no-op for HTTP client, but added for interface compliance).
     */
    async close(): Promise {
        logger.debug("Closing Keycloak admin client");
    }
}

# Kubernetes deployment readiness probe config for Keycloak 24
readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 15
  failureThreshold: 3
livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

# Keycloak CLI command to create conditional OTP policy for admin roles
kcadm.sh create authentication/flows/browser/executions \
  -r master \
  -s providerId=conditional-otp \
  -s requirement=OPTIONAL \
  -s displayName="Conditional OTP for Admins"

# Add role condition to the OTP policy
kcadm.sh create authentication/flows/browser/executions/{{executionId}}/config \
  -r master \
  -s alias="Admin OTP Condition" \
  -s config."user.roles"="admin,finance" \
  -s config."condition.type"="user-role"

// Spring Security config to cache JwtDecoder with Caffeine
@Bean
public JwtDecoder jwtDecoder() {
    NimbusJwtDecoder decoder = NimbusJwtDecoder.withJwkSetUri(KEYCLOAK_JWKS_URI).build();
    Cache jwksCache = Caffeine.newBuilder()
        .maximumSize(10)
        .expireAfterWrite(Duration.ofHours(1))
        .build();

    return token -> {
        try {
            return decoder.decode(token);
        } catch (JwtException e) {
            // Clear cache and retry once on key validation failure
            jwksCache.invalidateAll();
            decoder.getJwkSetCache().clear();
            return decoder.decode(token);
        }
    };
}