Tutorials
Migrating from Self-Hosted Keycloak

Migrating from Self-Hosted Keycloak

Migrate your existing Keycloak deployment to Skycloak with minimal downtime and zero data loss. This comprehensive guide walks you through migrating your users, configurations, themes, and extensions from self-hosted Keycloak to our fully managed platform.

Overview

Skycloak’s migration process helps you:

  • Transfer all user data including passwords and sessions
  • Preserve configurations for realms, clients, and roles
  • Migrate custom themes and branding
  • Move extensions and custom providers
  • Maintain domain names with zero downtime
  • Validate data integrity throughout the process

Why Migrate to Skycloak?

Eliminate Operational Overhead:

  • No more server management
  • Automatic updates and patches
  • Built-in backup and recovery
  • 24/7 monitoring and support

Reduce Costs:

  • No infrastructure expenses
  • Reduced DevOps requirements
  • Predictable monthly pricing
  • Included enterprise features

Improve Reliability:

  • 99.9% uptime SLA
  • Multi-region availability
  • Automatic scaling
  • DDoS protection included

Prerequisites

Before starting your migration:

Requirements Checklist

  • Skycloak account with Developer plan or higher
  • Admin access to your source Keycloak instance
  • Database export capabilities (PostgreSQL, MySQL, or H2)
  • Keycloak version 12.0 or higher (older versions need upgrade first)
  • Database type PostgreSQL, MySQL, or MariaDB
  • Backup of your current Keycloak data
  • Maintenance window scheduled (typically 2-4 hours)

Pre-Migration Assessment

Evaluate your current deployment:

  1. Check Keycloak version:

    ${KEYCLOAK_HOME}/bin/kc.sh version

  2. Assess database size:

    SELECT pg_database_size('keycloak') / 1024 / 1024 as size_mb;

  3. Count users and realms:

    SELECT COUNT(*) FROM user_entity;
SELECT COUNT(*) FROM realm;

  4. List custom providers:

    ls ${KEYCLOAK_HOME}/providers/

Migration Methods

Method 1: Database Export/Import (Recommended)

Best for: Complete migration with all data preserved

Method 2: Realm Export

Best for: Testing or partial migrations without user passwords

Step 1: Prepare Your Data

Export from Source Keycloak

Database Export (Recommended)

For PostgreSQL:

# Export complete database
pg_dump -h localhost -U keycloak -d keycloak \
  --no-owner --no-privileges \
  -f keycloak-backup.sql

# Compress for upload
gzip keycloak-backup.sql

For MySQL/MariaDB:

# Export with required flags
mysqldump -u keycloak -p keycloak \
  --single-transaction \
  --skip-lock-tables \
  --skip-add-drop-table \
  --complete-insert \
  --no-create-db \
  --skip-extended-insert \
  > keycloak-backup.sql

# Compress for upload (Required)
zip keycloak-backup.zip keycloak-backup.sql

Realm Export Alternative

If database export isn’t possible:

# Export specific realm
${KEYCLOAK_HOME}/bin/kc.sh export \
  --file=realm-export.json \
  --realm=your-realm

# Export all realms
${KEYCLOAK_HOME}/bin/kc.sh export \
  --file=all-realms.json

Prepare Theme Files

Package your custom themes:

# Navigate to themes directory
cd ${KEYCLOAK_HOME}/themes

# Create archive of custom themes
tar -czf custom-themes.tar.gz \
  my-theme-1/ my-theme-2/

Package Extensions

Collect custom providers and SPIs:

# Create extensions archive
cd ${KEYCLOAK_HOME}
tar -czf extensions.tar.gz \
  providers/*.jar \
  deployments/*.jar

Step 2: Start Migration Wizard

Access the Migration Tool

  1. Navigate to Migration in your Skycloak dashboard
  2. Click “Start New Migration”
  3. Select your target cluster or create a new one

Step 3: Upload Database

Database Upload Process

  1. Select your database file
  2. Choose source database type (PostgreSQL, MySQL, H2)
  3. Specify source Keycloak version
  4. Begin upload

Upload Validation

After upload, the system validates:

  • Database schema compatibility
  • Data integrity checks
  • User count verification
  • Realm structure validation

Step 4: Configure Domain (Optional)

Domain Migration Options

Maintain your existing domain with zero downtime:

  1. Keep existing domain (recommended)
  2. Use Skycloak subdomain temporarily
  3. Configure custom domain later

Zero-Downtime Migration

For seamless transition:

  1. Set up Skycloak cluster with temporary domain
  2. Import and verify all data
  3. Test thoroughly with temporary domain
  4. Update DNS to point to Skycloak
  5. Monitor during DNS propagation

Step 5: Migrate Themes (Optional)

Theme Migration

Upload and configure your custom themes:

  1. Upload theme package
  2. Select themes to migrate
  3. Map to applications

Theme Compatibility

The migration tool:

  • Checks theme compatibility with Keycloak version
  • Identifies missing dependencies
  • Suggests theme updates if needed
  • Preserves theme customizations

Step 6: Migrate Extensions (Optional)

Extension Compatibility

Upload custom providers and extensions:

Step 7: Review and Confirm

Pre-Migration Summary

Review all migration settings before proceeding:

Step 8: Migration Execution

Live Migration Progress

Monitor the migration in real-time:

Migration Stages

  1. Database Schema Creation (5 minutes)
  2. Realm Import (10 minutes)
  3. User Data Import (varies by size)
  4. Role and Group Import (5 minutes)
  5. Client Configuration (10 minutes)
  6. Theme Deployment (5 minutes)
  7. Extension Installation (10 minutes)
  8. Validation and Testing (15 minutes)

Step 9: Validation

Automatic Validation

The system automatically validates:

  • User count matches source
  • All realms imported correctly
  • Clients are functional
  • Roles and permissions preserved
  • Theme rendering correct

Manual Testing Checklist

Test critical functions:

  • Admin can login to Keycloak console
  • Users can authenticate successfully
  • Password validation works
  • SSO flow functions correctly
  • Custom themes display properly
  • Extensions operate as expected
  • API authentication works

Step 10: Go Live

DNS Cutover

For domain migration:

  1. Update DNS records:

    Type: CNAME
Host: auth.yourcompany.com
Target: your-cluster.skycloak.io
TTL: 300 (5 minutes for testing)

  2. Monitor DNS propagation:

    • Use tools like whatsmydns.net
    • Test from multiple locations
    • Monitor authentication logs

  3. Verify SSL certificates:

    • Automatic SSL provisioning
    • Certificate validation
    • HTTPS enforcement

Post-Migration Tasks

Immediate Actions

  1. Monitor closely for 24-48 hours
  2. Check performance metrics
  3. Review error logs
  4. Gather user feedback
  5. Update documentation

Optimization Opportunities

After successful migration:

  • Enable Skycloak-exclusive features
  • Optimize realm configurations
  • Implement enhanced security
  • Set up automated backups
  • Review analytics in the Insights dashboard

Rollback Plan

If Issues Occur

Have a rollback strategy ready:

  1. Keep source Keycloak running (read-only mode)
  2. Document rollback DNS settings
  3. Test rollback procedure before migration
  4. Have support contact ready

Rollback Steps

If needed:

  1. Revert DNS to original server
  2. Restore source Keycloak to active
  3. Investigate issues with Skycloak support
  4. Plan remediation before retry

Troubleshooting

Common Migration Issues

Large database timeout:

  • Split export into smaller chunks
  • Use realm-by-realm migration
  • Contact support for assisted migration

Theme compatibility errors:

  • Update theme to latest Keycloak version
  • Use Theme Library for rebuilding
  • Temporarily use default theme

Extension incompatibility:

  • Check for updated versions
  • Contact extension vendor
  • Consider Skycloak alternatives

User authentication failures:

  • Verify password encoding settings
  • Check realm security settings
  • Review client configurations

Migration Best Practices

Planning

  1. Schedule during low traffic
  2. Communicate with users in advance
  3. Have rollback plan ready
  4. Test in staging first if possible
  5. Document everything

Execution

  1. Take fresh backup before starting
  2. Monitor source system during migration
  3. Have support channel open
  4. Test incrementally after each stage
  5. Keep stakeholders informed

Post-Migration

  1. Monitor for 48 hours minimum
  2. Collect performance baseline
  3. Update disaster recovery plans
  4. Document new procedures
  5. Train team on Skycloak

Cost Considerations

Migration Costs

  • One-time migration: Free with Developer+ plans
  • Assisted migration: Available for Enterprise
  • Data transfer: No ingress charges
  • Temporary dual-running: Plan accordingly

Ongoing Savings

Calculate your ROI:

  • Eliminated infrastructure costs
  • Reduced DevOps time
  • Lower security overhead
  • Included feature value

Security During Migration

Data Protection

  • All transfers use TLS 1.3
  • Data encrypted at rest
  • Temporary files auto-deleted
  • Audit log of all operations
  • Compliance maintained throughout

Access Control

  • Migration requires admin rights
  • Temporary credentials auto-expire
  • All actions logged
  • IP restrictions available

Support Options

Self-Service Migration

Assisted Migration (Enterprise)

  • Dedicated migration specialist
  • Custom migration planning
  • Hands-on assistance
  • Post-migration optimization
  • 24/7 support during migration

Success Stories

Case Study Highlights

TechCorp: Migrated 50,000 users with zero downtime StartupXYZ: Reduced auth costs by 60% Enterprise Inc: Completed migration in 2 hours

Related Resources

Next Steps

After successful migration:

  1. Explore Skycloak features not available in self-hosted
  2. Optimize configurations for managed environment
  3. Review analytics in the Insights dashboard
  4. Plan disaster recovery procedures
  5. Schedule team training on Skycloak platform

Need Help?

  • Documentation: docs.skycloak.io
  • Support Portal: support.skycloak.io
  • Email: [email protected]
  • Enterprise Hotline: +1-555-SKYCLOAK
Email Theme Customization GuideSetting Up Enhanced Branding