Tutorials
Setting Up Enhanced Branding

Setting Up Enhanced Branding

This tutorial will guide you through setting up enhanced branding features in Skycloak, from basic customization to advanced theme uploads.

Prerequisites

  • Active Skycloak workspace
  • Running Keycloak cluster
  • Admin or owner role in workspace
  • Business+ plan for custom theme uploads

Step 1: Access Branding Settings

  1. Navigate to Your Cluster

    • Log in to Skycloak dashboard
    • Select your workspace
    • Click on your cluster name

  2. Open Branding Tab

    • Click the “Branding” tab
    • You’ll see the current branding configuration

Step 2: Basic Visual Customization

Company Information

  1. Add Company Details

    Company Name: Your Company Inc.

    This appears in the login page header

  2. Upload Logo

    • Click “Upload Logo” or provide URL
    • Recommended: 200x50px PNG with transparent background
    • Maximum file size: 500KB

  3. Set Favicon

    • Upload 32x32px icon
    • Appears in browser tabs

Color Scheme

  1. Primary Color

    • Click color picker or enter hex code
    • Example: #1976d2
    • Used for buttons and links

  2. Background Color

    • Default: #f5f5f5
    • Light colors recommended for readability

Text Customization

  1. Page Title

    Welcome to Your Company

    Main heading on login page

  2. Subtitle

    Sign in to access your account

    Supporting text below title

Step 3: Configure Links (Pro+ Plans)

  1. Terms of Service URL

    https://yourcompany.com/terms

  2. Privacy Policy URL

    https://yourcompany.com/privacy

These appear as footer links on all auth pages.

Step 4: Login Options

Configure authentication behavior:

  1. Enable User Registration

    • Toggle ON to allow self-registration
    • Toggle OFF for invite-only access

  2. Enable Password Reset

    • Toggle ON to show “Forgot Password?” link
    • Toggle OFF to disable self-service reset

  3. Show Remember Me

    • Toggle ON to display checkbox
    • Toggle OFF for higher security

Step 5: Preview Your Changes

Use the multi-page preview feature:

  1. Select Page Type

    • Login
    • Registration
    • Password Reset
    • OTP Configuration
    • OTP Login
    • Update Password

  2. Review Each Page

    • Check visual consistency
    • Verify text is readable
    • Test on different screen sizes

  3. Test Interactions

    • Click links to verify they work
    • Check form validation messages
    • Ensure all elements are visible

Step 6: Apply Changes

  1. Save Configuration

    • Click “Apply Branding”
    • Confirm the update

  2. Monitor Progress

    • Status shows “Updating…”
    • Wait 2-5 minutes for completion
    • Page will show “Active” when done

  3. Verify Live Changes

    • Open your Keycloak URL
    • Navigate to /realms/{realm}/account
    • Confirm branding is applied

Step 7: Custom Theme Upload (Business+)

Prepare Your Theme

  1. Create Theme Structure

    my-theme/
├── login/
│   ├── resources/
│   │   ├── css/
│   │   │   └── login.css
│   │   ├── img/
│   │   │   ├── logo.png
│   │   │   └── favicon.ico
│   │   └── js/
│   │       └── custom.js
│   ├── messages/
│   │   └── messages_en.properties
│   ├── login.ftl
│   ├── register.ftl
│   └── theme.properties
└── theme.properties

  2. Theme Configuration

    # theme.properties
parent=keycloak
import=common/keycloak

styles=css/login.css
scripts=js/custom.js

  3. Package Theme

    zip -r my-custom-theme.zip my-theme/

Upload Theme

  1. Navigate to Custom Themes

    • Go to Workspace Settings
    • Click “Custom Themes” tab

  2. Upload Theme Package

    • Click “Upload Custom Theme”
    • Select your ZIP file
    • Enter theme name
    • Click “Upload”

  3. Validate Upload

    • System validates theme structure
    • Check for any errors
    • Theme appears in list when successful

Apply Custom Theme

  1. Return to Cluster Branding

    • Navigate back to your cluster
    • Open Branding tab

  2. Select Custom Theme

    • Click “Use Custom Theme”
    • Select from uploaded themes
    • Preview the theme

  3. Apply Theme

    • Click “Apply Custom Theme”
    • Monitor update progress
    • Verify when complete

Step 8: Remove Powered By Badge (Launch+)

For Launch and Enterprise plans:

  1. Toggle Setting

    • Find “Show Powered by Skycloak”
    • Toggle OFF

  2. Apply Changes

    • Save configuration
    • Badge removed from all pages

Troubleshooting

Theme Not Updating

Problem: Changes don’t appear after applying

Solutions:

  1. Wait full 5 minutes for propagation
  2. Clear browser cache
  3. Check cluster status is “Available”
  4. Try in incognito/private browsing

Custom Theme Errors

Problem: Theme upload fails

Solutions:

  1. Verify ZIP structure matches requirements
  2. Check file size under 50MB
  3. Ensure login/ directory exists
  4. Validate FTL template syntax

Preview Not Loading

Problem: Preview shows error or blank

Solutions:

  1. Check all URLs use HTTPS
  2. Verify color codes are valid hex
  3. Ensure logos are accessible
  4. Refresh the page

Colors Not Applying

Problem: Colors remain default

Solutions:

  1. Use full hex codes (#RRGGBB)
  2. Avoid CSS color names
  3. Check for typos in values
  4. Test with standard colors first

Best Practices

Design Guidelines

  1. Accessibility

    • Maintain WCAG AA contrast ratios
    • Test with color blindness simulators
    • Ensure text remains readable

  2. Performance

    • Optimize images before upload
    • Use web-friendly formats (PNG, SVG)
    • Keep custom CSS minimal

  3. Consistency

    • Match your main website branding
    • Use same fonts and colors
    • Maintain visual hierarchy

Testing Checklist

Before going live:

  • Test on mobile devices
  • Verify all links work
  • Check form validation
  • Test error states
  • Verify email templates
  • Test with real users
  • Document customizations

Security Considerations

  1. URLs and Assets

    • Use HTTPS for all resources
    • Host assets on secure CDN
    • Validate all external resources

  2. Custom Themes

    • Avoid inline JavaScript
    • Sanitize user inputs
    • Follow Keycloak security guidelines

Advanced Configurations

Multi-Realm Branding

Apply different branding per realm:

  1. Create Realm-Specific Config

    • Each realm can have unique branding
    • Useful for multi-tenant scenarios

  2. Manage Through API

    PUT /api/clusters/{clusterId}/realms/{realmId}/branding

A/B Testing Themes

Test different branding variations:

  1. Upload Multiple Themes

    • Create variations of your theme
    • Upload each as separate package

  2. Switch Between Themes

    • Apply different themes to test
    • Monitor user engagement
    • Choose best performing option

Next Steps

Migrating from Self-Hosted KeycloakSetting Up Workspace SSO