Theme Library Setup Tutorial

This comprehensive tutorial will guide you through setting up and using Skycloak’s Theme Library, from initial configuration to advanced theme management across multiple applications.

Prerequisites

Active Skycloak workspace on the Business plan or higher
Running Keycloak cluster
Admin or owner role in workspace
Basic understanding of Keycloak theme structure (or a Keycloakify build to upload)

Step 1: Access Theme Library

Navigate to Theme Library

Open Skycloak Dashboard
- Log in to your Skycloak workspace
- Ensure you’re in the correct workspace
Access Theme Library
- Select your workspace, cluster, and realm in the sidebar
- Click “Themes” in the cluster navigation
- You’ll see the Theme Library management interface

Verify plan access

If you see an upgrade banner instead of the Theme Library interface:

Your workspace isn’t on the Business plan or higher
Contact your workspace owner to upgrade
Or reach out to sales@skycloak.io for pricing

Step 2: Prepare Your First Theme

Understanding Theme Structure

Before uploading, ensure your theme follows Keycloak conventions:

my-custom-theme/
├── login/                    # Login theme (most common)
│   ├── resources/
│   │   ├── css/
│   │   │   └── styles.css
│   │   ├── img/
│   │   │   ├── logo.png
│   │   │   └── favicon.ico
│   │   └── js/
│   │       └── custom.js
│   ├── messages/
│   │   ├── messages_en.properties
│   │   └── messages_es.properties
│   ├── login.ftl
│   ├── register.ftl
│   ├── login-reset-password.ftl
│   └── theme.properties
├── email/                    # Email theme (optional)
│   ├── html/
│   │   ├── email-verification.ftl
│   │   └── password-reset.ftl
│   ├── text/
│   │   ├── email-verification.ftl
│   │   └── password-reset.ftl
│   └── messages/
│       └── messages_en.properties
├── admin/                    # Admin theme (optional)
│   ├── resources/
│   │   ├── css/
│   │   │   └── admin-styles.css
│   │   └── img/
│   │       └── admin-logo.png
│   └── theme.properties
├── account/                  # Account theme (optional)
│   ├── resources/
│   │   ├── css/
│   │   │   └── account-styles.css
│   │   └── img/
│   │       └── account-logo.png
│   └── theme.properties
└── theme.properties         # Root theme configuration

Create Theme Configuration

Root theme.properties

# Theme metadata
name=My Custom Theme
version=1.0.0
description=Corporate branding theme

# Parent theme (optional)
parent=keycloak

Login theme.properties

parent=keycloak
import=common/keycloak

# Custom styles and scripts
styles=css/styles.css
scripts=js/custom.js

# Theme metadata
locales=en,es

Package Theme

# Create a ZIP package
zip -r my-custom-theme.zip my-custom-theme/

# Or, if you build with Keycloakify, use the generated JAR directly:
#   npx keycloakify build
# produces dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar

# Verify the archive (should be under 50MB)
ls -lh my-custom-theme.zip

Step 3: Upload Your First Theme

Upload Process

Start Upload
- Click “Upload Theme” button in Theme Library
- Select your theme archive — .zip or .jar (Keycloakify), max 50MB
- Wait for file upload to complete

Provide Theme Details

Theme Name: Corporate Branding
Version: 1.0.0
Description: Main corporate theme with login and email support

Automatic Type Detection
- System scans your theme structure
- Identifies supported theme types
- Displays detection results:
```
✓ Login Theme Detected
✓ Email Theme Detected
✗ Admin Theme Not Found
✗ Account Theme Not Found
```
Review Detection Results
- Login Theme: Detected from /login/ directory
- Email Theme: Detected from /email/ directory
- Admin Theme: Not detected (no /admin/ directory)
- Account Theme: Not detected (no /account/ directory)

Handle Detection Issues

If theme detection fails:

Check Theme Structure

# Verify required directories exist (works for both ZIP and JAR — both are ZIP containers)
unzip -l my-custom-theme.zip | grep -E "(login|email|admin|account)/"
# For a Keycloakify JAR:
unzip -l keycloak-theme-for-kc-all-other-versions.jar | grep -E "(login|email|admin|account)/"

Common Issues
- Missing required directories
- Incorrect file structure
- Missing theme.properties files
- Corrupted archive (ZIP or JAR)
Fix and Re-upload
- Correct the theme structure
- Re-create the archive (or rebuild with npx keycloakify build)
- Upload again

Step 4: Publish Your Theme

Publishing Process

Review Theme Details
- Check theme name and description
- Verify detected theme types
- Ensure all information is correct
Publish Theme
- Click “Publish Theme”
- Theme status changes to “Published”
- Theme becomes available for assignment
Verify Publication
- Theme appears in published themes list
- Status shows “Published”
- Available for application assignment

Theme Status Lifecycle

Draft: Recently uploaded, not published
Published: Available for assignment
Deployed: Assigned to one or more applications
Deprecated: Marked for removal

Step 5: Assign Theme to Application

Access Application Themes

Navigate to Application
- Go to Applications in your workspace
- Select the application you want to theme
- Click on the “Themes” tab
Review Current State
- See currently assigned themes
- Check for existing theme assignments
- Note any theme conflicts

Select Theme Type
- Click on “Login Theme” section
- View available published themes
- See theme preview if available
Choose Theme
- Select your published theme
- Preview theme assignment
- Click “Assign Theme”
Confirm Assignment
- Theme assignment is processed
- Status updates to “Assigned”
- Theme becomes active for the application

Assign Additional Theme Types

Email Theme Assignment
- Click on “Email Theme” section
- Warning: Check for email template conflicts
- Select appropriate email theme
- Review conflict warnings if any
Admin Theme Assignment
- Click on “Admin Theme” section
- Select admin theme if available
- Apply to admin console
Account Theme Assignment
- Click on “Account Theme” section
- Select account theme if available
- Apply to user account pages

Step 6: Handle Email Theme Conflicts

Understanding Email Conflicts

Email themes may conflict with custom email templates:

Custom Email Templates: Manually created email templates
Email Themes: Theme-based email templates
Conflict: Both trying to customize the same email type

Detect Conflicts

Automatic Detection
- System automatically scans for conflicts
- Warnings appear in Theme Library
- Conflict indicators shown on applications

Conflict Warning Example

⚠️  Email Theme Conflict Detected

Theme: Corporate Branding
Application: Customer Portal

Conflicting Templates:
- Email Verification (custom template exists)
- Password Reset (custom template exists)

Resolution Required

Resolve Conflicts

Option 1: Prioritize Theme
- Remove custom email templates
- Use theme-based email templates
- Consistent with overall theme
Option 2: Prioritize Custom Templates
- Remove email theme assignment
- Keep custom email templates
- Maintain current email behavior
Option 3: Hybrid Approach
- Use theme for some email types
- Use custom templates for others
- Requires careful management

Step 7: Test Theme Assignments

Testing Checklist

Login Theme Testing
- Navigate to application login page
- Verify branding is applied
- Test on mobile devices
- Check all authentication flows
Email Theme Testing
- Trigger email notifications
- Verify email styling
- Test different email types
- Check spam folder placement
Admin Theme Testing
- Access admin console
- Verify admin branding
- Test admin functionality
- Check all admin pages
Account Theme Testing
- Access user account pages
- Verify account branding
- Test account functionality
- Check profile management

Test Different Scenarios

User Flows
- New user registration
- Password reset flow
- Multi-factor authentication
Error Scenarios
- Invalid login attempts
- Expired password reset
- Account lockout
- Validation errors
Edge Cases
- Different browsers
- Mobile devices
- Slow connections
- JavaScript disabled

Step 8: Manage Multiple Themes

Organize Your Themes

Naming Convention

Corporate-Login-v1.0.0
Corporate-Email-v1.0.0
Corporate-Admin-v1.0.0
Marketing-Login-v1.0.0
Partner-Portal-v1.0.0

Version Management
- Use semantic versioning
- Document changes between versions
- Test before updating production
Theme Categories
- Primary Themes: Main corporate branding
- Application-Specific: Unique per application
- Experimental: A/B testing themes
- Legacy: Deprecated themes

Per-Application Strategy

Customer Portal
- Login Theme: Corporate branding
- Email Theme: Marketing-focused
- Account Theme: User-friendly
Admin Dashboard
- Login Theme: Simplified corporate
- Admin Theme: Streamlined interface
- No email theme needed
Partner Portal
- Login Theme: Partner co-branding
- Email Theme: Partner-specific
- Account Theme: Partnership-focused

Theme Assignment Matrix

Application	Login Theme	Email Theme	Admin Theme	Account Theme
Customer Portal	Corporate-v1.0	Marketing-v1.0	-	User-Friendly-v1.0
Admin Dashboard	Corporate-Simple-v1.0	-	Streamlined-v1.0	-
Partner Portal	Partner-Coop-v1.0	Partner-v1.0	-	Partnership-v1.0

Step 9: Update and Version Management

Updating Existing Themes

Create Updated Theme
- Modify your theme files
- Update version in theme.properties
- Test changes locally
Upload New Version
- Upload new ZIP with updated version
- System treats as new theme
- Old version remains available
Gradual Rollout
- Test new version on staging application
- Verify everything works correctly
- Update production applications

Version Control Best Practices

Documentation

Version 1.0.0 - Initial release
Version 1.1.0 - Added mobile responsiveness
Version 1.2.0 - Updated color scheme
Version 2.0.0 - Major redesign

Backup Strategy
- Keep all theme versions
- Document rollback procedures
- Test rollback process
Change Management
- Schedule theme updates
- Communicate changes to users
- Monitor for issues

Step 10: Advanced Features

Theme Analytics

Usage Tracking
- View theme usage across applications
- Monitor theme performance
- Track user engagement
Performance Metrics
- Theme load times
- User completion rates
- Error rates by theme

Multi-Environment Management

Environment Strategy
- Development: Test themes
- Staging: Preview themes
- Production: Stable themes
Promotion Workflow
- Test in development
- Validate in staging
- Promote to production

Troubleshooting

Common Issues

Theme Upload Fails

Problem: Upload fails with "Invalid theme structure"
Solution: Verify ZIP contains required directories

Type Detection Fails

Problem: No theme types detected
Solution: Check directory structure matches Keycloak conventions

Theme Not Applying

Problem: Theme assigned but not visible
Solution: The apply itself is nearly instant. If the change isn't visible,
         the most likely cause is edge caching — wait up to ~5 minutes
         or hard-refresh (Cmd/Ctrl+Shift+R). Verify the theme shows as
         "Deployed" in the library.

Email Conflicts

Problem: Email theme conflicts with custom templates
Solution: Choose resolution strategy (theme vs custom)

Getting Help

Skycloak Support
- Submit a ticket via support@skycloak.io
- Enterprise plans include faster response times and direct access to specialists
Documentation
- Theme Library reference guide
- Keycloak theme development docs
- Best practices documentation
Professional Services
- Custom theme development
- Migration assistance
- Training and consultation