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

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…”
   • Apply is nearly instant; the page will show “Active” once saved
   • If you don’t see the new look on your login page right away, that’s edge caching — give it up to ~5 minutes to clear, or hard-refresh (Cmd/Ctrl+Shift+R)

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 Theme Upload

   • Open your cluster’s Branding page
   • Expand the “Custom Theme” section

   For managing multiple themes across realms, see the Theme Library, which supports uploading several themes and assigning them per realm.

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. The apply itself is nearly instant; if the change isn’t visible, it’s almost always edge caching — give it up to ~5 minutes
2. If still missing after 5 minutes, hard-refresh (Cmd/Ctrl+Shift+R)
3. Check cluster status is “Available”
4. Try in incognito/private browsing to rule out a stale browser session

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 per Realm in the Dashboard

   • Switch between realms in the cluster’s Branding page
   • Edit each realm’s theme assignments and colors independently

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

• Configure custom domains
• Set up email templates
• Implement social login