Theme Library

The Theme Library is Skycloak’s advanced theme management system, available exclusively to Enterprise customers. It provides centralized theme management, automatic type detection, and application-specific theme assignments for complete customization control.

Overview

The Theme Library transforms how you manage Keycloak themes by providing:

Centralized Management: Upload and organize all your custom themes in one place
Automatic Type Detection: System automatically identifies login, email, admin, and account theme types
Application-Specific Assignment: Assign different themes to different applications
Version Control: Manage multiple versions of themes with rollback capabilities
Email Conflict Detection: Automatically detect and resolve email template conflicts
Usage Analytics: Track theme usage and performance across your organization

ℹ️

Enterprise Feature: The Theme Library is available exclusively with Enterprise plans. Contact sales to upgrade and access these advanced theming capabilities.

Theme Types

The Theme Library supports four distinct theme types, each serving different aspects of your Keycloak instance:

Login Themes

Purpose: Customize user-facing authentication pages

Login and registration forms
Password reset pages
Multi-factor authentication screens
Social login integration pages

Use Cases:

Brand consistency across authentication flows
Custom login experiences per application
A/B testing different authentication designs
Localized authentication pages

Email Themes

Purpose: Customize email templates sent to users

Welcome and verification emails
Password reset notifications
Account lockout alerts
Invitation emails

Use Cases:

Branded email communications
Custom email layouts and styling
Localized email content
Transactional email customization

Important: Email themes may conflict with custom email templates. The system automatically detects and warns about potential conflicts.

Admin Themes

Purpose: Customize the Keycloak admin console

Admin dashboard appearance
Configuration interface styling
Administrative workflow customization
White-label admin experiences

Use Cases:

Branded admin interfaces for managed services
Custom admin workflows
Simplified admin interfaces
Partner/client-specific admin experiences

Account Themes

Purpose: Customize user account management pages

User profile management
Account settings pages
Security settings interfaces
Personal information management

Use Cases:

Branded user self-service portals
Custom account management flows
Enhanced user experience
Integrated account management

Theme Management

Upload Process

Access Theme Library
- Navigate to Workspace Settings
- Click “Theme Library” tab
- Requires Enterprise plan
Upload Theme Package
- Click “Upload Theme”
- Select Keycloak theme ZIP file (max 50MB)
- Enter theme name and description
- System validates and processes upload
Automatic Type Detection
- System scans theme structure
- Identifies supported theme types
- Detects login, email, admin, and account components
- Reports detected capabilities
Theme Validation
- Validates Keycloak theme structure
- Checks for required files and templates
- Identifies potential issues
- Provides validation feedback
Publish Theme
- Review detected theme types
- Publish to make available for assignment
- Manage theme versions and updates

Theme Organization

Theme Listing:

View all uploaded themes
Filter by type (login, email, admin, account)
Search by name or description
Sort by upload date or usage

Theme Details:

Theme name and description
Detected theme types
File size and upload date
Usage statistics
Assignment status

Version Management:

Track theme versions
Update existing themes
Rollback to previous versions
Compare theme changes

Theme Status

Draft: Recently uploaded, not yet published Published: Available for assignment to applications Deployed: Currently assigned to one or more applications Deprecated: Marked for removal, not recommended for new assignments

Application Theme Assignment

Assignment Process

Navigate to Application
- Go to Application → Themes tab
- Enterprise plan required for theme assignment
Select Theme Type
- Choose from login, email, admin, or account
- View available themes for selected type
- See theme preview and details
Assign Theme
- Select theme from available options
- Preview theme assignment
- Apply theme to application
Manage Assignments
- View current theme assignments
- Update or remove theme assignments
- Monitor theme performance

Per-Application Theming

Flexible Assignment:

Assign different themes to different applications
Mix and match theme types per application
Override default themes for specific use cases

Assignment Examples:

Customer Portal: Custom login + account themes
Admin Dashboard: Admin theme only
Marketing Site: Login + email themes
Partner Portal: Complete custom theme set

Theme Conflicts

Email Theme Conflicts:

Automatically detected when email themes conflict with custom templates
Warning indicators on affected applications
Guidance for resolving conflicts
Option to prioritize themes or templates

Resolution Options:

Remove conflicting email theme
Disable custom email templates
Use theme-specific email templates
Contact support for advanced resolution

Enterprise Features

Advanced Management

Bulk Operations:

Upload multiple themes simultaneously
Bulk assign themes to applications
Mass update theme assignments
Batch delete unused themes

Analytics and Reporting:

Theme usage statistics
Performance metrics
User engagement analytics
Theme effectiveness reporting

A/B Testing:

Test different themes simultaneously
Compare theme performance
Gradual rollout capabilities
Data-driven theme optimization

Integration Capabilities

API Access:

RESTful API for theme management
Automated theme deployment
CI/CD pipeline integration
Third-party tool integration

Multi-Environment Support:

Development, staging, production themes
Environment-specific theme management
Synchronized theme deployment
Environment promotion workflows

Custom Development:

Theme development services
Custom theme creation
Migration assistance
Technical consulting

Support and Maintenance

Priority Support:

Dedicated theme support team
Technical assistance for complex themes
Migration and upgrade support
Performance optimization help

Professional Services:

Custom theme development
Theme migration from other systems
Training and best practices
Architecture and design consultation

Theme Development

Theme Structure

Standard Keycloak theme structure:

my-theme/
├── login/
│   ├── resources/
│   │   ├── css/
│   │   ├── img/
│   │   └── js/
│   ├── messages/
│   ├── *.ftl templates
│   └── theme.properties
├── email/
│   ├── html/
│   ├── text/
│   └── messages/
├── admin/
│   └── resources/
└── account/
    └── resources/

Theme Requirements

File Structure:

Must follow Keycloak theme conventions
Include theme.properties configuration
Contain appropriate template files
Support required message bundles

Type Detection:

Login: Requires login/ directory with templates
Email: Requires email/ directory with templates
Admin: Requires admin/ directory with resources
Account: Requires account/ directory with resources

Best Practices:

Test themes in development environment
Follow Keycloak security guidelines
Optimize images and assets
Document theme customizations

Testing Themes

Development Testing:

Local Keycloak instance testing
Multiple browser testing
Mobile responsiveness testing
Accessibility compliance testing

Staging Validation:

Upload to staging environment
Test with real user flows
Validate theme assignments
Check performance impact

Production Deployment:

Gradual rollout to applications
Monitor user feedback
Track performance metrics
Maintain rollback capability

Troubleshooting

Common Issues

Theme Upload Fails:

Check file size (max 50MB)
Verify ZIP file structure
Ensure valid Keycloak theme format
Check for corrupted files

Type Detection Issues:

Verify theme directory structure
Check for required template files
Ensure proper theme.properties configuration
Review error messages for specifics

Assignment Problems:

Confirm theme is published
Check application permissions
Verify theme type compatibility
Review conflict warnings

Email Conflicts:

Check for existing email templates
Review email theme assignments
Understand conflict resolution options
Contact support for complex scenarios

Error Messages

“Theme validation failed”:

Check Keycloak theme structure
Verify required files are present
Review theme.properties configuration
Check for syntax errors in templates

“Type detection failed”:

Ensure proper directory structure
Check for required template files
Verify theme.properties settings
Review theme naming conventions

“Assignment not allowed”:

Verify Enterprise plan access
Check application permissions
Confirm theme is published
Review plan limitations

Getting Help

Support Resources:

Enterprise support ticket system
Theme development documentation
Best practices guides

When Contacting Support:

Include theme files and error messages
Provide workspace and application details
Describe expected vs actual behavior
Include steps to reproduce issues

Plan Requirements

Enterprise Plan Benefits

Included Features:

Unlimited theme uploads
All theme types (login, email, admin, account)
Automatic type detection
Application-specific assignments
Email conflict detection
Usage analytics
API access
Priority support

Comparison with Other Plans:

Feature	Basic	Pro	Business	Enterprise
Basic Branding	✓	✓	✓	✓
Custom Theme Upload	-	-	✓	✓
Theme Library	-	-	-	✓
Multiple Theme Types	-	-	-	✓
Per-Application Themes	-	-	-	✓
Type Detection	-	-	-	✓
Email Conflict Detection	-	-	-	✓
Usage Analytics	-	-	-	✓
API Access	-	-	-	✓
Priority Support	-	-	✓	✓

Upgrade Process

Steps to Upgrade:

Contact sales team for Enterprise plan
Review feature requirements and pricing
Schedule migration and setup
Access Theme Library immediately after upgrade
Begin uploading and organizing themes

Migration Assistance:

Existing theme migration
Theme optimization consultation
Best practices training
Technical setup support

Next Steps

Security & Protection