Branding & Customization

Skycloak provides comprehensive branding and customization options to make your authentication experience seamlessly integrate with your brand. Customize everything from login pages to email templates to create a cohesive user experience.

Overview

The branding system in Skycloak allows you to:

• Custom Domains: Use your own domain for authentication
• Login Theme Customization: Modify login page appearance
• Email Branding: Customize email templates and SMTP settings
• Logo & Colors: Apply your brand identity across all user touchpoints

Custom Domains

Setting Up Custom Domains

Custom domains allow your users to authenticate using your own domain instead of the default Skycloak domain.

Benefits:

• Professional appearance (auth.yourcompany.com vs yourcompany.skycloak.io)
• Enhanced brand trust
• Consistent user experience
• SEO and marketing benefits

Requirements:

• Active paid plan (Developer or higher)
• Domain ownership verification
• DNS access for configuration

Setup Process:

1. Navigate to Branding → Domain in your workspace settings
2. Click “Add Custom Domain”
3. Enter your desired domain (e.g., auth.yourcompany.com)
4. Complete domain verification via DNS TXT record
5. Configure DNS CNAME record as instructed
6. Wait for SSL certificate provisioning (5-15 minutes)

Domain Management

Domain Status:

• Active: Domain is live and serving traffic
• Pending: Awaiting DNS verification or SSL provisioning
• Failed: Configuration error requiring attention

Domain Operations:

• Primary Domain: Set which domain is the default for new applications
• SSL Certificates: Automatically managed and renewed
• Multiple Domains: Add additional domains for different applications or environments

Login Theme Customization

Visual Customization

Customize the appearance of all Keycloak login pages including:

• Login and registration forms
• Password reset pages
• Multi-factor authentication screens
• OTP configuration and login pages
• Password update pages

Customization Options:

Company Branding:

• Company name displayed in login pages
• Custom logo (PNG, JPG, SVG supported)
• Favicon for browser tabs
• Automatic optimization for web delivery

Color Schemes:

• Background color for login pages
• Button color for primary actions
• Link colors inherited from button color
• Professional, clean design aesthetic

Footer Customization:

• Terms of Service link (optional)
• Privacy Policy link (optional)
• “Powered by Skycloak” branding (removable with Launch+ plans)

Login Options:

• Enable/disable user registration
• Enable/disable password reset
• Enable/disable “Remember Me” checkbox
• Real-time preview of all changes

Advanced Customization

For businesses and enterprise customers:

Custom Theme Upload (Business+ Plans):

• Upload complete Keycloak theme packages
• Full control over HTML templates and styling
• Support for custom JavaScript and CSS
• Version management for theme packages

Multi-Page Preview:

• Preview all authentication pages before publishing
• See how your branding appears across different flows
• Test responsive behavior on different screen sizes
• Instant preview updates as you make changes

Theme Download & Advanced Customization (Business & Enterprise Plans)

Overview

Business and Enterprise customers can download their current theme as a ZIP file, modify it locally using standard Keycloak theming practices, and re-upload it as a custom theme. This powerful workflow enables complete control over your authentication experience.

Download → Modify → Upload Workflow

1. Download Your Current Theme

• Navigate to Branding page for your realm
• In the Custom Theme section, click “Download Theme”
• Receive a ZIP file containing your current branding configuration
• The theme includes all your current customizations

2. Extract and Explore Theme Structure

your-theme/
├── login/
│   ├── theme.properties        # Theme configuration
│   ├── login.ftl               # Login page template
│   ├── register.ftl            # Registration page
│   ├── login-reset-password.ftl # Password reset
│   ├── login-otp.ftl           # OTP configuration
│   ├── login-update-password.ftl # Password update
│   └── resources/
│       ├── css/
│       │   └── styles.css      # Custom styles
│       └── img/                # Logos and images
└── email/
    └── html/                   # Email templates

3. Modify Theme Files

Working with FreeMarker Templates (.ftl)

FreeMarker templates control the HTML structure and content of your authentication pages. These templates use a powerful templating language that allows dynamic content and logic.

Common FreeMarker Variables:

${realm.displayName!''}         # Your realm's display name
${msg("loginAccountTitle")}     # Internationalized message
${url.loginAction}              # Form action URLs
${url.registrationUrl}          # Registration link
${properties.customProperty!'default'} # Custom properties with default
${client.name!''}               # Application name
${social.providers?has_content} # Check if social providers exist

Example Customizations:

Adding a Custom Welcome Message:

<!-- In login.ftl -->
<div class="custom-welcome">
    <h1>Welcome to ${realm.displayName!'Our Platform'}</h1>
    <p class="subtitle">Secure authentication for your enterprise</p>
</div>

Customizing Form Labels:

<!-- Override default username label -->
<label for="username" class="custom-label">
    ${msg("usernameOrEmail")}
    <span class="required">*</span>
</label>

Adding Conditional Content:

<#if realm.registrationAllowed && !registrationDisabled??>
    <div class="registration-prompt">
        <p>New to our platform?</p>
        <a href="${url.registrationUrl}" class="signup-link">
            Create an account
        </a>
    </div>
</#if>

Customizing Fonts and Typography

Adding Custom Fonts:

1. Google Fonts (in styles.css):

@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');

body {
    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

h1, h2, h3 {
    font-weight: 600;
    letter-spacing: -0.02em;
}

2. Self-Hosted Fonts (add to resources/fonts/):

@font-face {
    font-family: 'CustomFont';
    src: url('../fonts/CustomFont.woff2') format('woff2'),
         url('../fonts/CustomFont.woff') format('woff');
    font-weight: normal;
    font-style: normal;
}

Customizing Page Text and Messages

Using theme.properties for Text Variables:

# Custom text variables
loginTitle=Welcome Back
loginSubtitle=Sign in to continue to your account
registerTitle=Create Your Account
registerSubtitle=Join thousands of satisfied users
customFooterText=© 2024 Your Company. All rights reserved.
termsText=By signing in, you agree to our
privacyText=We respect your

Reference in Templates:

<h1>${properties.loginTitle!'Sign In'}</h1>
<p class="subtitle">${properties.loginSubtitle!''}</p>

Creating Custom Message Bundles:

1. Create messages/messages_en.properties:

loginAccountTitle=Sign in to Your Account
emailVerifyTitle=Email Verification Required
customError=Oops! Something went wrong. Please try again.
passwordRequirements=Password must be at least 12 characters

2. Reference in templates:

<div class="error-message">
    ${msg("customError")}
</div>

Advanced Template Customizations

Adding Custom JavaScript:

<!-- In login.ftl, before closing body tag -->
<script>
    // Password strength indicator
    document.getElementById('password')?.addEventListener('input', function(e) {
        const strength = calculatePasswordStrength(e.target.value);
        updateStrengthIndicator(strength);
    });
    
    // Custom form validation
    document.getElementById('kc-form-login')?.addEventListener('submit', function(e) {
        if (!validateCustomRules()) {
            e.preventDefault();
            showCustomError('Please complete all required fields');
        }
    });
</script>

Mobile-Responsive Modifications:

/* Responsive design improvements */
@media (max-width: 768px) {
    .login-container {
        padding: 20px;
        max-width: 100%;
    }
    
    .custom-logo {
        max-width: 150px;
    }
    
    input[type="text"],
    input[type="password"] {
        font-size: 16px; /* Prevent zoom on iOS */
    }
}

Testing Your Modified Theme

Local Keycloak Testing:

1. Set up local Keycloak instance (Docker recommended)
2. Copy theme to themes/ directory
3. Select theme in realm settings
4. Test all authentication flows

Testing Checklist:

• ✓ Login page renders correctly
• ✓ Registration flow works
• ✓ Password reset emails sent
• ✓ OTP/MFA pages functional
• ✓ Mobile responsive design
• ✓ Accessibility compliance (WCAG 2.1)
• ✓ Cross-browser compatibility

Re-uploading as Custom Theme

1. Prepare Theme Package:

   • Ensure all modified files are included
   • Verify theme.properties is present
   • ZIP the theme directory

2. Upload to Skycloak:

   • Navigate to Branding → Custom Theme
   • Click “Upload Theme”
   • Select your modified ZIP file
   • Wait for validation and deployment

3. Apply and Test:

   • Click “Apply Branding” to deploy
   • Test all authentication flows
   • Verify customizations are working

Best Practices

Version Control:

# Track theme changes in Git
git init my-theme
git add .
git commit -m "Initial theme version"
git tag v1.0.0

Documentation:

• Document all customizations
• Keep a changelog of modifications
• Note any JavaScript additions
• List custom CSS classes

Performance:

• Optimize images (use WebP/AVIF)
• Minify CSS and JavaScript
• Lazy load non-critical resources
• Keep total theme size under 10MB

Security:

• Sanitize all user inputs in JavaScript
• Avoid inline scripts when possible
• Use Content Security Policy headers
• Never expose sensitive data in templates

Reference Documentation

• Keycloak Theme Documentation: https://www.keycloak.org/docs/latest/server_development/#_themes
• FreeMarker Template Language: https://freemarker.apache.org/docs/
• Keycloak Theme Examples: https://github.com/keycloak/keycloak/tree/main/themes

Troubleshooting

Common Issues:

Theme Not Updating:

• Clear browser cache
• Check for syntax errors in FTL files
• Verify theme.properties formatting
• Ensure ZIP structure is correct

Template Syntax Errors:

Error: Expected hash but was string
Solution: Check FreeMarker syntax, ensure proper use of ${} vs <#>

Missing Resources:

Error: 404 for CSS/images
Solution: Verify paths in theme.properties and resource references

Custom Fonts Not Loading:

• Check CORS headers if using external fonts
• Verify font file paths are correct
• Ensure font formats are web-compatible

Theme Library (Enterprise Plans)

Overview

The Theme Library is an advanced feature available exclusively to Enterprise customers that provides comprehensive theme management capabilities:

• Centralized Theme Management: Upload and manage multiple custom themes in one place
• Type-Specific Themes: Support for login, email, admin, and account page themes
• Automatic Type Detection: Automatically identifies what types of pages each theme supports
• Application-Specific Assignment: Assign different themes to different applications
• Version Control: Track and manage multiple versions of your themes
• Email Conflict Detection: Automatically detect and resolve email template conflicts

Theme Types

The Theme Library supports four distinct theme types:

Login Themes:

• Customize login, registration, and password reset pages
• Apply to user-facing authentication flows
• Most commonly used theme type

Email Themes:

• Customize email templates sent to users
• Includes welcome emails, password resets, and notifications
• May conflict with custom email templates

Admin Themes:

• Customize the Keycloak admin console appearance
• Apply to administrative interfaces
• Useful for white-label solutions

Account Themes:

• Customize user account management pages
• Apply to user profile and settings pages
• Enhance user self-service experience

Theme Upload Process

1. Navigate to Theme Library

   • Go to Workspace Settings → Theme Library
   • Enterprise plan required

2. Upload Theme Package

   • Click “Upload Theme”
   • Select your Keycloak theme ZIP file (max 50MB)
   • System automatically detects theme types
   • Provide theme name and description

3. Theme Validation

   • System validates theme structure
   • Checks for required files and templates
   • Identifies supported theme types
   • Reports any issues or conflicts

4. Publish Theme

   • Review theme details and detected types
   • Publish theme to make it available for assignment
   • Manage theme versions and updates

Application Theme Assignment

Per-Application Theming:

• Assign different themes to different applications
• Mix and match theme types (login + email, admin only, etc.)
• Override default themes for specific use cases

Theme Assignment Process:

1. Navigate to Application → Themes tab
2. Select theme type (login, email, admin, account)
3. Choose from available published themes
4. Apply theme to the application
5. Preview and test the changes

Theme Conflict Resolution:

• System automatically detects email theme conflicts
• Provides warnings and resolution guidance
• Helps maintain email template consistency

Enterprise Features

Advanced Theme Management:

• Bulk theme operations
• Theme usage analytics
• Performance monitoring
• A/B testing capabilities

Integration Features:

• API access for theme management
• Automated theme deployment
• CI/CD pipeline integration
• Multi-environment theme sync

Support and Maintenance:

• Priority support for theme issues
• Theme migration assistance
• Custom theme development services
• Professional services available

Theme Library vs Basic Branding

Getting Started with Theme Library

1. Upgrade to Enterprise

   • Contact sales for Enterprise plan
   • Access Theme Library features immediately

2. Prepare Your Themes

   • Create or modify existing Keycloak themes
   • Ensure themes follow Keycloak standards
   • Test themes in development environment

3. Upload and Organize

   • Upload themes to Theme Library
   • Organize by type and purpose
   • Document theme usage and dependencies

4. Assign to Applications

   • Review each application’s theming needs
   • Assign appropriate themes per application
   • Test and validate theme assignments

For detailed Theme Library documentation, see the Theme Library Guide.

Theme Preview

Use the enhanced preview system to see changes before publishing:

• Multi-Page Preview: Switch between login, registration, password reset, OTP, and update password pages
• Live Preview: See changes in real-time as you modify settings
• Realm Settings Integration: Preview shows/hides elements based on login options
• Mobile Preview: Test responsive behavior
• Instant Updates: No need to save to see preview changes

Email Customization

Email Templates

Customize all automated emails sent by your Keycloak instance:

Available Templates:

• Welcome emails for new user registration
• Email verification for account confirmation
• Password reset emails
• MFA setup notifications
• Account lockout alerts
• Invitation emails for workspace members

Customization Features:

• HTML and plain text versions
• Dynamic content insertion (user name, links, etc.)
• Responsive email design
• Multi-language support
• A/B testing capabilities (Enterprise)

SMTP Configuration

Configure your own SMTP server for email delivery:

Supported Providers:

• Custom SMTP servers
• SendGrid, Mailgun, Amazon SES
• Gmail, Outlook (for development)
• Enterprise email systems

Configuration Steps:

1. Navigate to Branding → Email in workspace settings
2. Choose “Custom SMTP” or select a provider
3. Enter SMTP server details:
   • Host: SMTP server hostname
   • Port: Usually 587 (TLS) or 465 (SSL)
   • Username: SMTP authentication username
   • Password: SMTP authentication password
   • Encryption: TLS/SSL settings
4. Configure sender details:
   • From Name: Display name for outgoing emails
   • From Email: Sender email address
   • Reply-To: Reply address (optional)
5. Test configuration with a test email
6. Save and activate

SMTP Testing:

• Built-in test email functionality
• Delivery verification
• Error diagnosis and troubleshooting
• Performance monitoring

Email Analytics

Track email performance with built-in analytics:

• Delivery rates and bounce tracking
• Open rates and click-through rates
• Template performance comparison
• Error tracking and debugging

Brand Guidelines

Design Best Practices

Visual Consistency:

• Use your brand colors consistently across all elements
• Maintain proper logo proportions and spacing
• Ensure sufficient color contrast for accessibility
• Test on multiple devices and screen sizes

User Experience:

• Keep forms simple and focused
• Provide clear error messages and instructions
• Ensure fast loading times
• Test user flows thoroughly

Brand Safety:

• Use high-resolution logos and graphics
• Maintain brand guidelines compliance
• Consider cultural and accessibility implications
• Test with real users when possible

Accessibility Compliance

Skycloak’s branding system supports accessibility best practices:

• WCAG 2.1 compliance features
• Color contrast validation
• Screen reader compatibility
• Keyboard navigation support
• Alternative text for images

Managing Branding

All branding and customization features are managed through the Skycloak dashboard:

Theme Customization:

1. Navigate to your cluster in the dashboard
2. Click on the Branding tab
3. Configure your branding settings:
   • Enter your company name
   • Add logo and favicon URLs
   • Select background and button colors
   • Add Terms of Service and Privacy Policy links
   • Configure login options (registration, password reset, remember me)
4. Preview changes across different page types
5. Click Apply Branding to save

Important Notes:

• Theme updates take 2-5 minutes to apply
• During updates, cluster modifications are temporarily blocked
• You’ll receive real-time progress updates
• Preview is instant and doesn’t require saving

Apply to All Realms

For organizations managing multiple realms within a cluster, Skycloak provides a convenient “Apply to All Realms” feature:

Overview: The “Apply to All Realms” feature allows you to copy branding settings from one realm to all other realms in the same cluster. This ensures consistent branding across your entire authentication infrastructure.

Required Workflow:

1. Configure branding for your primary realm
2. Click “Apply Branding” to save your changes - This step is required!
3. Wait for the branding to be applied (2-5 minutes)
4. Once saved, the “Apply to All Realms” button becomes available
5. Click the button to open the configuration modal
6. Select which elements to copy:
   • Branding Settings: Logo, colors, text, and footer links
   • Custom Theme: Your uploaded custom theme (if applicable)
   • Login Options: Registration, password reset, remember me settings
7. Choose realms to exclude (optional)
8. Click Apply to propagate settings

Important Note: The “Apply to All Realms” button is disabled when you have unsaved changes. You must first apply your branding changes to the current realm before you can propagate them to other realms. This ensures that the source realm has the latest saved configuration.

What Gets Copied:

• Visual branding (logos, colors, fonts)
• Page titles and subtitles
• Footer links (Terms of Service, Privacy Policy)
• Custom theme assignments
• Login page options and settings
• The exact theme names from Keycloak ensuring consistency

Technical Details:

• The feature reads the actual theme names from the source realm in Keycloak
• Applies those exact theme names to all target realms
• Copies the database configuration for UI consistency
• No theme redeployment needed - themes are already in the container

Best Practices:

• Configure and test branding on a single realm first
• Use the preview feature to verify appearance
• Consider excluding test or development realms
• The master realm is always excluded for security

Notes:

• This operation updates both Keycloak configuration and the Skycloak database
• Changes are applied sequentially to each realm
• Progress is tracked and reported in real-time
• Failed realms are reported with error details for troubleshooting

Custom Theme Upload (Business+ Plans):

1. Navigate to Workspace Settings → Custom Themes
2. Click Upload Theme
3. Select your Keycloak theme ZIP file
4. Validate and upload the theme
5. Apply the theme to any cluster from the Branding page

Troubleshooting

Common Issues

Custom Domain Not Working:

• Verify DNS records are correctly configured
• Check domain verification status
• Ensure SSL certificate has been issued
• Contact support if issues persist after 24 hours

Email Delivery Problems:

• Test SMTP configuration with test email
• Check spam folders and email filters
• Verify sender reputation and authentication
• Review SMTP provider documentation

Theme Not Applying:

• Wait for the full update process to complete (2-5 minutes)
• Check cluster status is “Available” before making changes
• Clear browser cache and cookies
• Verify all URLs are HTTPS and accessible
• For custom themes, ensure theme structure is valid

Preview Not Updating:

• Check that all form fields have valid values
• Ensure color values are in hex format (#RRGGBB)
• Verify URLs are properly formatted
• Try refreshing the page if preview stops responding

Getting Help

Support Resources:

• Built-in help documentation in the dashboard
• Email support for paid plans
• Documentation and guides

When Contacting Support:

• Include workspace ID and domain details
• Provide error messages or screenshots
• Describe steps to reproduce the issue
• Include browser and device information

Advanced Features

Multi-Environment Branding

For organizations with multiple environments:

• Development environments with staging branding
• Production environments with full branding
• A/B testing different brand variations
• Region-specific branding and localization

Integration Features

Single Sign-On (SSO) Branding:

• Consistent branding across all integrated applications
• Centralized theme management
• Automatic brand propagation to new applications

White-Label Solutions:

• Complete brand customization for resellers
• Custom domain and branding for clients
• Isolated branding management
• Enterprise licensing options

Next Steps

• Set up your first custom domain
• Customize email templates
• Explore the Theme Library
• Explore application integration