Tutorials
Theme Library Setup Tutorial

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)
ℹ️
Plan requirement: The Theme Library is available on the Business and Enterprise plans. If you’re on a lower plan, upgrade from Workspace Settings → Billing, or contact sales.

Step 1: Access Theme Library

Navigate to Theme Library

  1. Open Skycloak Dashboard

    • Log in to your Skycloak workspace
    • Ensure you’re in the correct workspace

  2. Access Theme Library

    • Click on “Workspace Settings” in the sidebar
    • Select the “Theme Library” tab
    • 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 [email protected] 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

  1. Root theme.properties

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

# Parent theme (optional)
parent=keycloak

  2. 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

  3. 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

  1. 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

  2. Provide Theme Details

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

  3. 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

  4. 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:

  1. 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)/"

  2. Common Issues

    • Missing required directories
    • Incorrect file structure
    • Missing theme.properties files
    • Corrupted archive (ZIP or JAR)

  3. 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

  1. Review Theme Details

    • Check theme name and description
    • Verify detected theme types
    • Ensure all information is correct

  2. Publish Theme

    • Click “Publish Theme”
    • Theme status changes to “Published”
    • Theme becomes available for assignment

  3. 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

  1. Navigate to Application

    • Go to Applications in your workspace
    • Select the application you want to theme
    • Click on the “Themes” tab

  2. Review Current State

    • See currently assigned themes
    • Check for existing theme assignments
    • Note any theme conflicts

Assign Login Theme

  1. Select Theme Type

    • Click on “Login Theme” section
    • View available published themes
    • See theme preview if available

  2. Choose Theme

    • Select your published theme
    • Preview theme assignment
    • Click “Assign Theme”

  3. Confirm Assignment

    • Theme assignment is processed
    • Status updates to “Assigned”
    • Theme becomes active for the application

Assign Additional Theme Types

  1. Email Theme Assignment

    • Click on “Email Theme” section
    • Warning: Check for email template conflicts
    • Select appropriate email theme
    • Review conflict warnings if any

  2. Admin Theme Assignment

    • Click on “Admin Theme” section
    • Select admin theme if available
    • Apply to admin console

  3. 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

  1. Automatic Detection

    • System automatically scans for conflicts
    • Warnings appear in Theme Library
    • Conflict indicators shown on applications

  2. 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

  1. Option 1: Prioritize Theme

    • Remove custom email templates
    • Use theme-based email templates
    • Consistent with overall theme

  2. Option 2: Prioritize Custom Templates

    • Remove email theme assignment
    • Keep custom email templates
    • Maintain current email behavior

  3. 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

  1. Login Theme Testing

    • Navigate to application login page
    • Verify branding is applied
    • Test on mobile devices
    • Check all authentication flows

  2. Email Theme Testing

    • Trigger email notifications
    • Verify email styling
    • Test different email types
    • Check spam folder placement

  3. Admin Theme Testing

    • Access admin console
    • Verify admin branding
    • Test admin functionality
    • Check all admin pages

  4. Account Theme Testing

    • Access user account pages
    • Verify account branding
    • Test account functionality
    • Check profile management

Test Different Scenarios

  1. User Flows

    • New user registration
    • Password reset flow
    • Multi-factor authentication

  2. Error Scenarios

    • Invalid login attempts
    • Expired password reset
    • Account lockout
    • Validation errors

  3. Edge Cases

    • Different browsers
    • Mobile devices
    • Slow connections
    • JavaScript disabled

Step 8: Manage Multiple Themes

Organize Your Themes

  1. 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

  2. Version Management

    • Use semantic versioning
    • Document changes between versions
    • Test before updating production

  3. Theme Categories

    • Primary Themes: Main corporate branding
    • Application-Specific: Unique per application
    • Experimental: A/B testing themes
    • Legacy: Deprecated themes

Per-Application Strategy

  1. Customer Portal

    • Login Theme: Corporate branding
    • Email Theme: Marketing-focused
    • Account Theme: User-friendly

  2. Admin Dashboard

    • Login Theme: Simplified corporate
    • Admin Theme: Streamlined interface
    • No email theme needed

  3. 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

  1. Create Updated Theme

    • Modify your theme files
    • Update version in theme.properties
    • Test changes locally

  2. Upload New Version

    • Upload new ZIP with updated version
    • System treats as new theme
    • Old version remains available

  3. Gradual Rollout

    • Test new version on staging application
    • Verify everything works correctly
    • Update production applications

Version Control Best Practices

  1. 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

  2. Backup Strategy

    • Keep all theme versions
    • Document rollback procedures
    • Test rollback process

  3. Change Management

    • Schedule theme updates
    • Communicate changes to users
    • Monitor for issues

Step 10: Advanced Features

Theme Analytics

  1. Usage Tracking

    • View theme usage across applications
    • Monitor theme performance
    • Track user engagement

  2. Performance Metrics

    • Theme load times
    • User completion rates
    • Error rates by theme

Multi-Environment Management

  1. Environment Strategy

    • Development: Test themes
    • Staging: Preview themes
    • Production: Stable themes

  2. Promotion Workflow

    • Test in development
    • Validate in staging
    • Promote to production

Troubleshooting

Common Issues

  1. Theme Upload Fails

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

  2. Type Detection Fails

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

  3. 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.

  4. Email Conflicts

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

Getting Help

  1. Skycloak Support

    • Submit a ticket via [email protected]
    • Enterprise plans include faster response times and direct access to specialists

  2. Documentation

    • Theme Library reference guide
    • Keycloak theme development docs
    • Best practices documentation

  3. Professional Services

    • Custom theme development
    • Migration assistance
    • Training and consultation

Best Practices Summary

Theme Development

  • Follow Keycloak theme conventions
  • Test themes thoroughly before upload
  • Use semantic versioning
  • Document all customizations

Management

  • Organize themes by purpose and application
  • Use clear naming conventions
  • Implement gradual rollout strategies
  • Monitor theme performance

Testing

  • Test all authentication flows
  • Verify on multiple devices
  • Check email delivery and formatting
  • Validate accessibility compliance

Security

  • Avoid inline JavaScript
  • Sanitize all user inputs
  • Use HTTPS for all resources
  • Follow Keycloak security guidelines

Next Steps

Pro Tip: Start with a simple login theme to familiarize yourself with the Theme Library workflow before moving to complex multi-type themes.
Last updated on
JWT Token Validation Best PracticesImplementing Magic Link Authentication