Multi-Realm Architecture Patterns

@Service
public class RealmManagementService {
    
    private final Keycloak keycloakAdmin;
    private final RealmTemplateService templateService;
    
    public RealmManagementService(KeycloakProperties props) {
        this.keycloakAdmin = KeycloakBuilder.builder()
            .serverUrl(props.getServerUrl())
            .realm("master")
            .clientId("admin-cli")
            .clientSecret(props.getAdminSecret())
            .build();
    }
    
    public RealmRepresentation createTenantRealm(TenantConfig config) {
        try {
            // Generate unique realm name
            String realmName = generateRealmName(config.getTenantId());
            
            // Get base template
            RealmRepresentation realm = templateService.getTemplate(config.getPlan());
            
            // Customize for tenant
            realm.setRealm(realmName);
            realm.setDisplayName(config.getCompanyName());
            realm.setEnabled(true);
            
            // Set realm-specific settings
            customizeRealmSettings(realm, config);
            
            // Create realm
            keycloakAdmin.realms().create(realm);
            
            // Post-creation setup
            setupRealmDefaults(realmName, config);
            
            return realm;
            
        } catch (Exception e) {
            throw new RealmCreationException("Failed to create realm", e);
        }
    }
    
    private void customizeRealmSettings(RealmRepresentation realm, TenantConfig config) {
        // Security settings
        realm.setPasswordPolicy(getPasswordPolicyForPlan(config.getPlan()));
        realm.setBruteForceProtected(true);
        realm.setPermanentLockout(false);
        realm.setMaxFailureWaitSeconds(900);
        realm.setMaxDeltaTimeSeconds(43200);
        
        // Token settings
        realm.setAccessTokenLifespan(config.getTokenLifespan());
        realm.setSsoSessionMaxLifespan(config.getSessionLifespan());
        
        // Feature flags
        Map<String, String> attributes = new HashMap<>();
        attributes.put("plan", config.getPlan());
        attributes.put("features", String.join(",", config.getEnabledFeatures()));
        realm.setAttributes(attributes);
        
        // Branding
        if (config.getTheme() != null) {
            realm.setLoginTheme(config.getTheme());
            realm.setEmailTheme(config.getTheme());
        }
    }
    
    private void setupRealmDefaults(String realmName, TenantConfig config) {
        RealmResource realm = keycloakAdmin.realm(realmName);
        
        // Create default roles
        createDefaultRoles(realm);
        
        // Create default groups
        createDefaultGroups(realm);
        
        // Create service accounts
        createServiceAccounts(realm, config);
        
        // Configure identity providers
        if (config.getIdentityProviders() != null) {
            configureIdentityProviders(realm, config.getIdentityProviders());
        }
        
        // Set up event listeners
        configureEventListeners(realm);
    }
    
    private void createDefaultRoles(RealmResource realm) {
        List<RoleRepresentation> defaultRoles = Arrays.asList(
            createRole("tenant-admin", "Tenant Administrator"),
            createRole("tenant-user", "Regular User"),
            createRole("tenant-viewer", "Read-only User")
        );
        
        defaultRoles.forEach(role -> 
            realm.roles().create(role)
        );
    }
    
    private RoleRepresentation createRole(String name, String description) {
        RoleRepresentation role = new RoleRepresentation();
        role.setName(name);
        role.setDescription(description);
        role.setComposite(false);
        return role;
    }
}

@Component
public class MultiRealmAuthenticationFilter extends OncePerRequestFilter {
    
    private final RealmResolver realmResolver;
    private final TokenValidator tokenValidator;
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, 
                                  HttpServletResponse response, 
                                  FilterChain filterChain) throws ServletException, IOException {
        
        try {
            // Resolve realm from request
            String realm = realmResolver.resolveRealm(request);
            
            if (realm == null) {
                response.sendError(HttpServletResponse.SC_BAD_REQUEST, "Unable to determine realm");
                return;
            }
            
            // Set realm context
            RealmContext.setCurrentRealm(realm);
            
            // Validate token for specific realm
            String token = extractToken(request);
            if (token != null) {
                DecodedJWT jwt = tokenValidator.validateTokenForRealm(token, realm);
                SecurityContext context = createSecurityContext(jwt, realm);
                SecurityContextHolder.setContext(context);
            }
            
            filterChain.doFilter(request, response);
            
        } finally {
            // Clean up
            RealmContext.clear();
            SecurityContextHolder.clearContext();
        }
    }
}

@Component
public class RealmResolver {
    
    public String resolveRealm(HttpServletRequest request) {
        // Strategy 1: Subdomain-based
        String host = request.getServerName();
        if (host.endsWith(".myapp.com")) {
            return host.substring(0, host.indexOf(".myapp.com"));
        }
        
        // Strategy 2: Path-based
        String path = request.getRequestURI();
        if (path.startsWith("/tenants/")) {
            String[] parts = path.split("/");
            if (parts.length > 2) {
                return parts[2];
            }
        }
        
        // Strategy 3: Header-based
        String realmHeader = request.getHeader("X-Tenant-Realm");
        if (realmHeader != null) {
            return realmHeader;
        }
        
        // Strategy 4: JWT claim
        String token = extractToken(request);
        if (token != null) {
            try {
                DecodedJWT jwt = JWT.decode(token);
                return jwt.getClaim("realm").asString();
            } catch (Exception e) {
                // Invalid token, try other strategies
            }
        }
        
        return null;
    }
}

@Service
public class CrossRealmService {
    
    private final Map<String, Keycloak> realmClients = new ConcurrentHashMap<>();
    
    public void executeInRealm(String realm, Consumer<RealmResource> action) {
        Keycloak client = getOrCreateClient(realm);
        RealmResource realmResource = client.realm(realm);
        
        try {
            action.accept(realmResource);
        } catch (Exception e) {
            throw new CrossRealmException("Failed to execute in realm: " + realm, e);
        }
    }
    
    public <T> T queryAcrossRealms(List<String> realms, 
                                  Function<RealmResource, T> query,
                                  BinaryOperator<T> combiner) {
        return realms.parallelStream()
            .map(realm -> {
                try {
                    Keycloak client = getOrCreateClient(realm);
                    return query.apply(client.realm(realm));
                } catch (Exception e) {
                    logger.error("Failed to query realm: " + realm, e);
                    return null;
                }
            })
            .filter(Objects::nonNull)
            .reduce(combiner)
            .orElse(null);
    }
    
    // Example: Count users across all realms
    public long getTotalUserCount(List<String> realms) {
        return queryAcrossRealms(
            realms,
            realm -> (long) realm.users().count(),
            Long::sum
        );
    }
    
    // Example: Search users across realms
    public List<UserRepresentation> searchUsersAcrossRealms(String search) {
        List<String> realms = getAllTenantRealms();
        
        return realms.parallelStream()
            .flatMap(realm -> {
                try {
                    return getOrCreateClient(realm)
                        .realm(realm)
                        .users()
                        .search(search, 0, 10)
                        .stream()
                        .map(user -> {
                            user.setAttributes(
                                Map.of("source_realm", realm)
                            );
                            return user;
                        });
                } catch (Exception e) {
                    return Stream.empty();
                }
            })
            .collect(Collectors.toList());
    }
}

@Component
public class RealmTemplateService {
    
    private final Map<String, RealmTemplate> templates = new HashMap<>();
    
    @PostConstruct
    public void initializeTemplates() {
        templates.put("starter", createStarterTemplate());
        templates.put("professional", createProfessionalTemplate());
        templates.put("enterprise", createEnterpriseTemplate());
    }
    
    private RealmTemplate createStarterTemplate() {
        return RealmTemplate.builder()
            .name("Starter Plan Template")
            .passwordPolicy("length(8) and specialChars(1) and digits(1)")
            .maxUsers(1000)
            .maxClients(5)
            .features(Arrays.asList("basic-auth", "social-login"))
            .tokenLifespan(300) // 5 minutes
            .sessionLifespan(1800) // 30 minutes
            .build();
    }
    
    private RealmTemplate createEnterpriseTemplate() {
        return RealmTemplate.builder()
            .name("Enterprise Plan Template")
            .passwordPolicy("length(12) and specialChars(2) and digits(2) and upperCase(1)")
            .maxUsers(-1) // Unlimited
            .maxClients(-1) // Unlimited
            .features(Arrays.asList(
                "basic-auth", 
                "social-login", 
                "mfa", 
                "user-federation",
                "custom-flows",
                "advanced-analytics"
            ))
            .tokenLifespan(900) // 15 minutes
            .sessionLifespan(28800) // 8 hours
            .identityProviders(Arrays.asList(
                createSAMLProvider(),
                createOIDCProvider()
            ))
            .customAuthFlows(Arrays.asList(
                "progressive-profiling",
                "risk-based-auth"
            ))
            .build();
    }
    
    public RealmRepresentation applyTemplate(String templateName, String realmName) {
        RealmTemplate template = templates.get(templateName);
        if (template == null) {
            throw new IllegalArgumentException("Unknown template: " + templateName);
        }
        
        RealmRepresentation realm = new RealmRepresentation();
        realm.setRealm(realmName);
        realm.setEnabled(true);
        
        // Apply template settings
        realm.setPasswordPolicy(template.getPasswordPolicy());
        realm.setAccessTokenLifespan(template.getTokenLifespan());
        realm.setSsoSessionMaxLifespan(template.getSessionLifespan());
        
        // Set attributes for feature flags
        Map<String, String> attributes = new HashMap<>();
        attributes.put("max_users", String.valueOf(template.getMaxUsers()));
        attributes.put("max_clients", String.valueOf(template.getMaxClients()));
        attributes.put("enabled_features", String.join(",", template.getFeatures()));
        attributes.put("template", templateName);
        realm.setAttributes(attributes);
        
        return realm;
    }
}

@RestController
@RequestMapping("/api/admin/realms")
public class RealmManagementController {
    
    private final RealmManagementService realmService;
    private final RealmMetricsService metricsService;
    
    @GetMapping
    public ResponseEntity<List<RealmInfo>> listRealms(
            @RequestParam(required = false) String status,
            @RequestParam(required = false) String plan) {
        
        List<RealmInfo> realms = realmService.getAllRealms().stream()
            .filter(realm -> status == null || realm.getStatus().equals(status))
            .filter(realm -> plan == null || realm.getPlan().equals(plan))
            .map(this::enrichWithMetrics)
            .collect(Collectors.toList());
        
        return ResponseEntity.ok(realms);
    }
    
    @GetMapping("/{realmId}/metrics")
    public ResponseEntity<RealmMetrics> getRealmMetrics(@PathVariable String realmId) {
        RealmMetrics metrics = metricsService.getMetrics(realmId);
        return ResponseEntity.ok(metrics);
    }
    
    @PostMapping("/{realmId}/suspend")
    public ResponseEntity<Void> suspendRealm(@PathVariable String realmId) {
        realmService.suspendRealm(realmId);
        return ResponseEntity.noContent().build();
    }
    
    @DeleteMapping("/{realmId}")
    public ResponseEntity<Void> deleteRealm(
            @PathVariable String realmId,
            @RequestParam(defaultValue = "false") boolean immediate) {
        
        if (immediate) {
            realmService.deleteRealmImmediately(realmId);
        } else {
            realmService.scheduleRealmDeletion(realmId, 30); // 30 days
        }
        
        return ResponseEntity.noContent().build();
    }
    
    private RealmInfo enrichWithMetrics(RealmInfo realm) {
        try {
            RealmMetrics metrics = metricsService.getQuickMetrics(realm.getId());
            realm.setUserCount(metrics.getUserCount());
            realm.setActiveUsers(metrics.getActiveUsers());
            realm.setStorageUsed(metrics.getStorageUsed());
        } catch (Exception e) {
            logger.warn("Failed to get metrics for realm: " + realm.getId(), e);
        }
        return realm;
    }
}

@Service
public class RealmMetricsService {
    
    private final MeterRegistry meterRegistry;
    private final Cache<String, RealmMetrics> metricsCache;
    
    @Scheduled(fixedDelay = 60000) // Every minute
    public void collectMetrics() {
        List<String> realms = getAllRealmIds();
        
        realms.parallelStream().forEach(realmId -> {
            try {
                RealmMetrics metrics = collectRealmMetrics(realmId);
                metricsCache.put(realmId, metrics);
                
                // Update Prometheus metrics
                updatePrometheusMetrics(realmId, metrics);
            } catch (Exception e) {
                logger.error("Failed to collect metrics for realm: " + realmId, e);
            }
        });
    }
    
    private void updatePrometheusMetrics(String realmId, RealmMetrics metrics) {
        meterRegistry.gauge("keycloak_realm_users", 
            Tags.of("realm", realmId), metrics.getUserCount());
        
        meterRegistry.gauge("keycloak_realm_active_sessions", 
            Tags.of("realm", realmId), metrics.getActiveSessions());
        
        meterRegistry.gauge("keycloak_realm_storage_bytes", 
            Tags.of("realm", realmId), metrics.getStorageUsed());
    }
}

@Configuration
public class RealmCacheConfig {
    
    @Bean
    public CacheManager realmCacheManager() {
        CaffeineCacheManager cacheManager = new CaffeineCacheManager();
        cacheManager.setCaffeine(Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(Duration.ofMinutes(5))
            .recordStats());
        return cacheManager;
    }
    
    @Bean
    public RealmCache realmCache() {
        return new RealmCache() {
            private final LoadingCache<String, RealmData> cache = Caffeine.newBuilder()
                .maximumSize(500)
                .expireAfterWrite(5, TimeUnit.MINUTES)
                .refreshAfterWrite(2, TimeUnit.MINUTES)
                .build(this::loadRealm);
            
            private RealmData loadRealm(String realmId) {
                // Load from Keycloak
                return keycloakService.getRealmData(realmId);
            }
            
            @Override
            public RealmData get(String realmId) {
                return cache.get(realmId);
            }
            
            @Override
            public void invalidate(String realmId) {
                cache.invalidate(realmId);
            }
        };
    }
}

@Configuration
public class KeycloakConnectionConfig {
    
    @Bean
    public KeycloakConnectionPool connectionPool() {
        return new KeycloakConnectionPool(
            PoolConfig.builder()
                .maxTotal(100)
                .maxPerRoute(10)
                .connectionTimeout(Duration.ofSeconds(5))
                .socketTimeout(Duration.ofSeconds(30))
                .build()
        );
    }
    
    @Bean
    public KeycloakClientFactory clientFactory(KeycloakConnectionPool pool) {
        return new KeycloakClientFactory() {
            private final Map<String, Keycloak> clients = new ConcurrentHashMap<>();
            
            @Override
            public Keycloak getClient(String realm) {
                return clients.computeIfAbsent(realm, r -> 
                    createPooledClient(r, pool)
                );
            }
            
            private Keycloak createPooledClient(String realm, KeycloakConnectionPool pool) {
                return KeycloakBuilder.builder()
                    .serverUrl(keycloakUrl)
                    .realm(realm)
                    .clientId(clientId)
                    .clientSecret(clientSecret)
                    .resteasyClient(pool.getClient())
                    .build();
            }
        };
    }
}

@Aspect
@Component
public class RealmIsolationAspect {
    
    @Around("@annotation(RealmIsolated)")
    public Object enforceRealmIsolation(ProceedingJoinPoint joinPoint) throws Throwable {
        String currentRealm = RealmContext.getCurrentRealm();
        
        if (currentRealm == null) {
            throw new SecurityException("No realm context set");
        }
        
        // Extract realm from method arguments
        Object[] args = joinPoint.getArgs();
        String targetRealm = extractTargetRealm(args);
        
        if (targetRealm != null && !targetRealm.equals(currentRealm)) {
            throw new SecurityException(
                "Access denied: Cannot access realm " + targetRealm + 
                " from realm " + currentRealm
            );
        }
        
        return joinPoint.proceed();
    }
}

// Usage
@Service
public class UserService {
    
    @RealmIsolated
    public User getUser(String realmId, String userId) {
        // Method can only access users from current realm
        return userRepository.findByRealmAndId(realmId, userId);
    }
}

@Component
public class RealmAuditLogger {
    
    @EventListener
    public void handleRealmEvent(RealmEvent event) {
        AuditEntry entry = AuditEntry.builder()
            .timestamp(Instant.now())
            .eventType(event.getType())
            .realmId(event.getRealmId())
            .userId(event.getUserId())
            .details(event.getDetails())
            .ipAddress(event.getIpAddress())
            .userAgent(event.getUserAgent())
            .build();
        
        // Store in realm-specific audit log
        auditRepository.save(entry);
        
        // Alert on suspicious activity
        if (isSuspicious(event)) {
            alertService.sendSecurityAlert(entry);
        }
    }
    
    private boolean isSuspicious(RealmEvent event) {
        return event.getType() == EventType.REALM_DELETED ||
               event.getType() == EventType.MASS_USER_DELETION ||
               event.getType() == EventType.ADMIN_PERMISSION_CHANGED;
    }
}

public class RealmNamingStrategy {
    
    public String generateRealmName(TenantInfo tenant) {
        // Format: environment-region-tenantId
        return String.format("%s-%s-%s",
            tenant.getEnvironment().toLowerCase(),
            tenant.getRegion().toLowerCase(),
            tenant.getId().toLowerCase()
        );
    }
    
    // Examples:
    // prod-us-acme-corp
    // staging-eu-test-company
    // dev-asia-demo-tenant
}

@Component
public class RealmQuotaEnforcer {
    
    @Before("@annotation(RequiresQuotaCheck)")
    public void enforceQuota(JoinPoint joinPoint) {
        String realm = RealmContext.getCurrentRealm();
        RealmQuota quota = quotaService.getQuota(realm);
        
        // Check various limits
        if (isCreatingUser(joinPoint) && quota.isUserLimitReached()) {
            throw new QuotaExceededException("User limit reached for realm");
        }
        
        if (isCreatingClient(joinPoint) && quota.isClientLimitReached()) {
            throw new QuotaExceededException("Client limit reached for realm");
        }
    }
}

@Service
public class RealmBackupService {
    
    @Scheduled(cron = "0 0 2 * * *") // 2 AM daily
    public void backupAllRealms() {
        List<String> realms = realmService.getAllRealmIds();
        
        realms.parallelStream().forEach(realmId -> {
            try {
                RealmRepresentation export = exportRealm(realmId);
                String backupPath = storeBackup(realmId, export);
                
                logger.info("Backed up realm {} to {}", realmId, backupPath);
            } catch (Exception e) {
                logger.error("Failed to backup realm: " + realmId, e);
            }
        });
    }
    
    public void restoreRealm(String realmId, String backupId) {
        RealmRepresentation backup = loadBackup(realmId, backupId);
        
        // Delete existing realm
        keycloak.realm(realmId).remove();
        
        // Recreate from backup
        keycloak.realms().create(backup);
        
        logger.info("Restored realm {} from backup {}", realmId, backupId);
    }
}

@SpringBootTest
public class MultiRealmIntegrationTest {
    
    @Autowired
    private RealmManagementService realmService;
    
    private List<String> testRealms = new ArrayList<>();
    
    @BeforeEach
    public void setupTestRealms() {
        // Create test realms
        for (int i = 0; i < 3; i++) {
            String realmId = "test-realm-" + i;
            realmService.createRealm(realmId);
            testRealms.add(realmId);
        }
    }
    
    @AfterEach
    public void cleanupTestRealms() {
        testRealms.forEach(realm -> {
            try {
                realmService.deleteRealm(realm);
            } catch (Exception e) {
                // Ignore
            }
        });
    }
    
    @Test
    public void testCrossRealmIsolation() {
        // Create user in realm 1
        String userId = createUser(testRealms.get(0), "user1");
        
        // Try to access from realm 2 - should fail
        RealmContext.setCurrentRealm(testRealms.get(1));
        
        assertThrows(SecurityException.class, () -> {
            userService.getUser(testRealms.get(0), userId);
        });
    }
    
    @Test
    public void testRealmSpecificConfiguration() {
        // Configure different settings per realm
        testRealms.forEach(realm -> {
            RealmSettings settings = new RealmSettings();
            settings.setPasswordPolicy("length(" + (8 + testRealms.indexOf(realm)) + ")");
            realmService.updateSettings(realm, settings);
        });
        
        // Verify each realm has its own settings
        for (int i = 0; i < testRealms.size(); i++) {
            RealmSettings settings = realmService.getSettings(testRealms.get(i));
            assertEquals("length(" + (8 + i) + ")", settings.getPasswordPolicy());
        }
    }
}