tessl/maven-org-apereo-cas--cas-server-support-themes

Apereo CAS Web Application Themes Support - Provides comprehensive theme resolution and management capabilities for the Central Authentication Service

—

Pending

Overview

Eval results

Files

Header-Based Theme Resolution

Name: tessl/maven-org-apereo-cas--cas-server-support-themes
Author: tessl

Simple theme resolution that extracts theme names from HTTP request headers.

Capabilities

RequestHeaderThemeResolver

Theme resolver that extracts theme from HTTP request headers using a configured header name.

/**
 * Theme resolver that extracts theme from HTTP request headers
 */
public class RequestHeaderThemeResolver extends AbstractThemeResolver {
    
    /**
     * Constructor with header name configuration
     * @param themeHeaderName Name of HTTP header to check for theme value
     */
    public RequestHeaderThemeResolver(String themeHeaderName);
    
    /**
     * Resolves theme from request header
     * @param request HTTP request containing theme header
     * @return Theme name from header, or default theme if header missing/empty
     */
    @Nonnull
    @Override
    public String resolveThemeName(HttpServletRequest request);
    
    /**
     * No-op implementation for theme setting
     * @param httpServletRequest HTTP request
     * @param httpServletResponse HTTP response
     * @param theme Theme name
     */
    @Override
    public void setThemeName(@Nonnull HttpServletRequest httpServletRequest,
                           HttpServletResponse httpServletResponse, String theme);
}

Usage Examples:

import org.apereo.cas.services.web.RequestHeaderThemeResolver;

// Create header-based theme resolver
RequestHeaderThemeResolver headerResolver = new RequestHeaderThemeResolver("X-CAS-Theme");
headerResolver.setDefaultThemeName("default");

// Resolve theme from request
String themeName = headerResolver.resolveThemeName(request);

// Example HTTP request with theme header:
// GET /cas/login HTTP/1.1
// Host: cas.example.com
// X-CAS-Theme: dark
// 
// Result: themeName = "dark"

Header Configuration

Standard Header Names

Common header names used for theme selection:

// Common theme header patterns
new RequestHeaderThemeResolver("X-Theme");           // Generic
new RequestHeaderThemeResolver("X-CAS-Theme");       // CAS-specific  
new RequestHeaderThemeResolver("X-UI-Theme");        // UI-specific
new RequestHeaderThemeResolver("Theme");             // Simple
new RequestHeaderThemeResolver("X-Client-Theme");    // Client-specific

Custom Header Names

Any valid HTTP header name can be used:

// Examples of custom header configurations
new RequestHeaderThemeResolver("X-Brand-Theme");
new RequestHeaderThemeResolver("X-Tenant-Theme");  
new RequestHeaderThemeResolver("X-Mobile-Theme");
new RequestHeaderThemeResolver("Preferred-Theme");

Integration Patterns

API-Driven Theme Selection

Ideal for API clients that need to specify themes programmatically:

POST /cas/v1/tickets HTTP/1.1
Host: cas.example.com
Content-Type: application/json
X-CAS-Theme: api-minimal

{
  "username": "user@example.com",
  "password": "secret"
}

Mobile App Integration

Mobile applications can specify appropriate themes:

GET /cas/login?service=https://mobile.example.com HTTP/1.1
Host: cas.example.com
User-Agent: MyMobileApp/1.0
X-CAS-Theme: mobile-dark

Multi-Tenant Applications

Different tenants can specify their themes:

GET /cas/login?service=https://tenant1.example.com HTTP/1.1
Host: cas.example.com  
X-Tenant-Theme: tenant1-corporate

Load Balancer Integration

Load balancers can add theme headers based on routing rules:

# Nginx configuration example
location /cas/login {
    proxy_pass http://cas-backend;
    
    # Add theme header based on host
    if ($host = "admin.example.com") {
        proxy_set_header X-CAS-Theme "admin";
    }
    if ($host = "mobile.example.com") {
        proxy_set_header X-CAS-Theme "mobile";
    }
}

Theme Resolution Behavior

Header Processing

Case Sensitive: Header names are case-sensitive
First Value: Uses first header value if multiple headers present
Trim Whitespace: Theme values are trimmed of leading/trailing whitespace
Empty Headers: Empty or whitespace-only headers treated as missing

Default Theme Fallback

Returns default theme when:

Header is not present in request
Header value is empty or whitespace-only
Header value is null

// Example resolution logic
String headerValue = request.getHeader(themeHeaderName);
if (StringUtils.isBlank(headerValue)) {
    return getDefaultThemeName();  // "default"
}
return headerValue.trim();

Security Considerations

Header Validation

The resolver performs minimal validation:

No theme name validation against available themes
No sanitization of header values
No protection against header injection

Recommended Practices

Theme Validation: Validate themes exist at theme source level
Input Sanitization: Sanitize theme names before use
Allowlist Themes: Maintain allowlist of valid theme names
Header Security: Use secure header naming conventions

// Example theme validation wrapper
public class ValidatingHeaderThemeResolver extends RequestHeaderThemeResolver {
    private final Set<String> validThemes;
    
    @Override
    public String resolveThemeName(HttpServletRequest request) {
        String theme = super.resolveThemeName(request);
        if (validThemes.contains(theme)) {
            return theme;
        }
        return getDefaultThemeName();
    }
}

Request Context Integration

Request Attribute Storage

When used in ChainingThemeResolver, resolved themes are stored as request attributes:

// Theme stored as request attribute for later use
String attributeName = casProperties.getTheme().getParamName(); // Default: "theme"
request.setAttribute(attributeName, resolvedTheme);

Spring Web MVC Integration

Works seamlessly with Spring Web MVC theme resolution:

// Spring controller can access resolved theme
@Controller
public class LoginController {
    
    @RequestMapping("/login")
    public String login(HttpServletRequest request, Model model) {
        String theme = (String) request.getAttribute("theme");
        model.addAttribute("currentTheme", theme);
        return "login";
    }
}

Performance Characteristics

Very Fast: Simple header lookup with minimal processing
No I/O: No file system or network access required
Stateless: No session or persistence overhead
Cache Friendly: Results can be cached per request if needed

Common Use Cases

API Authentication: REST clients specifying themes
Mobile Applications: Native apps requesting mobile-optimized themes
Multi-Brand Platforms: Different brands specifying their themes
A/B Testing: Experimental themes via header injection
Load Balancer Routing: Infrastructure-level theme assignment
Development/Testing: Easy theme switching during development

Install with Tessl CLI

npx tessl i tessl/maven-org-apereo-cas--cas-server-support-themes

docs

auto-configuration.md

header-theme-resolution.md

index.md

service-theme-resolution.md

theme-resolution.md

theme-sources.md

tile.json