Complete Guide: Migrating Legacy Wizbrand Users to Keycloak & Customizing Email Templates

When you integrated Keycloak SSO into Wizbrand, new users began being created in both Wizbrand and Keycloak.
However, existing users (created before Keycloak integration) only exist in Wizbrand’s database.
To unify authentication, we need to migrate old users into Keycloak while keeping their Wizbrand data intact.

This tutorial explains:

1. How to migrate existing users into Keycloak with automation
2. How to handle email verification / password reset flows
3. How to add a “no-email” mode (so users reset passwords during next login)
4. How to fix redirect & email-sending errors
5. How to fully customize Keycloak’s email UI to a modern, branded template

Architecture Summary

Files Involved

Updated Migration Command

Here’s the final version of app/Console/Commands/MigrateUsersToKeycloak.php
It includes:

• --no-email → skip sending emails
• --lifespan → custom expiry time
• Graceful error handling
• No method renaming or removal

(You already have this updated version; keep it as your base.)

Key usage examples:

# Normal migration + verification email
php artisan kc:migrate --limit=50 --email-verify

# Send emails with a 30-day valid link
php artisan kc:migrate --limit=50 --email-verify --lifespan=2592000

# Skip emails; users reset password on next login
php artisan kc:migrate --limit=50 --email-verify --no-email

Understanding Each Option

Common Errors & Fixes

Invalid Redirect URI

Error:

Invalid redirect uri

Fix:

1. In Keycloak → Clients → wizbrand-web
2. Add your redirect: http://wz-account-admin-ms/auth/callback
3. Save and re-run your command.

Invalid Sender Address ‘null’

Error:

Failed to send execute actions email: Invalid sender address 'null'

Fix:
Configure SMTP in Realm Settings → Email

Tip — Infinite Token is NOT Possible

Keycloak action links (password reset, verification) are JWT-based and must expire.
However, you can:

• Extend their lifespan (e.g., 30–90 days) using: --lifespan=2592000
• Set a global default:
  • Realm Settings → Tokens → Default Admin-Initiated Action Lifespan → 30d

Forcing Reset at Next Login (No Email)

When --no-email is used:

• No email link is sent.
• Keycloak sets UPDATE_PASSWORD and VERIFY_EMAIL as required actions.
• User will be forced to reset password during their next login.

To verify:

1. Go to Users → [user] → Required Actions
2. You’ll see: UPDATE_PASSWORD VERIFY_EMAIL
3. After user completes reset, list becomes empty.

Customizing the Email Design (Wizbrand Branded)

The default email looks basic.
You can fully rebrand it to match Wizbrand’s identity.

Folder Structure

/opt/keycloak/themes/wizbrand/
├─ theme.properties
├─ messages/messages_en.properties
└─ email/
   ├─ html/execute-actions.ftl
   └─ text/execute-actions.ftl

theme.properties

parent=keycloak
types=email
locales=en

HTML Template (Beautiful Modern UI)

email/html/execute-actions.ftl

(abridged summary — full version above in chat)

Features:

• Wizbrand logo & dark header
• Clean card layout
• “Continue & secure my account” button
• Action list (e.g., Update Password, Verify Email)
• Expiry notice & fallback link
• Responsive design (works in Gmail, Outlook, Apple Mail)

Plain Text Fallback

email/text/execute-actions.ftl — simple message body for clients that block HTML.

Select Theme in Keycloak

1. Go to Realm Settings → Themes
2. Set Email Theme = wizbrand
3. Save
4. Restart Keycloak if needed --spi-theme-cache-themes=false --spi-theme-cache-templates=false

Preview of the Styled Email (Conceptually)

(You can imagine this layout)

╔══════════════════════════════════════╗
║ Wizbrand Logo                        ║
╠══════════════════════════════════════╣
║  Action required to secure your account
║  Click below to reset your credentials
║  [ Continue & Secure My Account ]     ║
║  This link expires in 30 days.        ║
╠══════════════════════════════════════╣
║  Need help? Contact support@wizbrand.com
╚══════════════════════════════════════╝

Folder Path & Permissions (Linux/Docker)

If Keycloak runs in Docker:

docker cp ./wizbrand keycloak:/opt/keycloak/themes/wizbrand
docker exec -it keycloak chmod -R 755 /opt/keycloak/themes/wizbrand
docker restart keycloak

If self-hosted on Linux:

sudo mkdir -p /opt/keycloak/themes/wizbrand
sudo chown -R keycloak:keycloak /opt/keycloak/themes/wizbrand
sudo systemctl restart keycloak

Optional Enhancements

Verification Checklist

Key Benefits Achieved

Seamless migration of legacy users
Stronger password reset and verification enforcement
Optional email-less password reset
100% branded, professional email communication
Automated, repeatable process for future imports

Example: Full Command Lifecycle

Initial Import

php artisan kc:migrate --limit=100 --email-verify --lifespan=2592000

If SMTP fails

php artisan kc:migrate --limit=100 --email-verify --no-email

Weekly resend pending resets

php artisan kc:resend-actions --verify --lifespan=604800

Final Outcome

After completing this setup:

• All Wizbrand users (old + new) are in Keycloak.
• New users use standard registration.
• Old users either:
  • Receive a Wizbrand-branded email to reset credentials, or
  • Are forced to reset at next login (no email mode).
• Emails now look professional and consistent with Wizbrand’s identity.