Zeros and OnesLLC
Migration5 min read

Migrating from Self-Hosted Keycloak to TitaniumVault

A guide for teams moving from self-managed Keycloak to TitaniumVault. Keep the features you love without the operational overhead.

By Zeros and Ones Team•

title: "Migrating from Self-Hosted Keycloak to TitaniumVault" description: "A guide for teams moving from self-managed Keycloak to TitaniumVault. Keep the features you love without the operational overhead." date: "2025-01-09" author: "Zeros and Ones Team" category: "Migration" tags: ["Keycloak", "Migration", "TitaniumVault", "Self-Hosted", "Open Source"]

Self-hosting Keycloak gives you complete control, but it also means managing infrastructure, updates, and scaling yourself. If your team is spending too much time on identity infrastructure instead of building your product, it might be time to consider a managed alternative.

Why Teams Move from Self-Hosted Keycloak

Common motivations:

  1. Operational Burden: Patching, scaling, and maintenance take significant DevOps time
  2. High Availability: Setting up and maintaining HA Keycloak requires expertise
  3. Support: Community support can be slow for critical issues
  4. Feature Gaps: Enterprise features require additional development
  5. Cost: Total cost of ownership (infrastructure + personnel) often exceeds managed solutions

What You'll Keep vs. What Changes

Features That Translate Well

  • User Federation: LDAP/AD sync works similarly
  • Identity Brokering: Social and enterprise IdP connections
  • OIDC/SAML: Standard protocol support
  • Roles and Groups: Permission modeling
  • Client Scopes: Token customization

Features That Work Differently

  • Custom Themes: TitaniumVault has its own theming system
  • Authentication Flows: Different configuration approach
  • SPIs and Extensions: Custom code needs migration
  • Admin Events: Audit logging structure differs

Pre-Migration Assessment

Document Your Setup

Realms and Clients:

# Export realm configuration
/opt/keycloak/bin/kc.sh export --realm=your-realm --dir=/export

User Count and Federation:

  • Total local users
  • Federated users (LDAP/AD)
  • User attributes
  • Custom user storage providers

Authentication Flows:

  • Custom flows
  • Required actions
  • Conditional OTP
  • WebAuthn settings

Extensions:

  • Custom SPIs
  • Event listeners
  • Custom authenticators
  • Theme modifications

Migration Approach

Option 1: Managed Migration (Recommended)

Use TitaniumVault's migration assistance to handle the heavy lifting.

Process:

  1. Export Keycloak configuration
  2. TitaniumVault team analyzes and maps features
  3. Parallel setup and testing
  4. Coordinated cutover

Option 2: Self-Service Migration

Handle migration yourself using APIs and tools.

Process:

  1. Set up TitaniumVault
  2. Replicate configuration manually
  3. Export/import users
  4. Update applications
  5. Test and cutover

Step-by-Step Migration

Phase 1: TitaniumVault Setup

  1. Create organization

    • Configure custom domain
    • Set up SSL certificates
    • Configure email settings

  2. Replicate realm settings

    • Create equivalent policies
    • Configure login settings
    • Set up branding

  3. Set up identity providers

    • Configure social connections
    • Set up SAML/OIDC brokers
    • Connect LDAP/AD

Phase 2: Client Migration

Export client configurations from Keycloak:

# Get all clients via Admin API
curl -X GET \
  "http://localhost:8080/admin/realms/YOUR_REALM/clients" \
  -H "Authorization: Bearer $TOKEN"

Create equivalent applications in TitaniumVault:

# Create application
curl -X POST \
  "https://api.titanium-vault.com/v1/applications" \
  -H "Authorization: Bearer $TV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application",
    "type": "oidc",
    "redirectUris": ["https://app.example.com/callback"],
    "allowedScopes": ["openid", "profile", "email"]
  }'

Phase 3: User Export

Export users from Keycloak:

# Export users via API
curl -X GET \
  "http://localhost:8080/admin/realms/YOUR_REALM/users?max=1000" \
  -H "Authorization: Bearer $TOKEN"

For large user bases, use the export feature:

# Full realm export including users
/opt/keycloak/bin/kc.sh export \
  --realm=your-realm \
  --users=realm_file \
  --dir=/export

Phase 4: User Import

Transform and import users:

// Transform Keycloak user to TitaniumVault
const transformUser = (kcUser) => ({
  email: kcUser.email,
  emailVerified: kcUser.emailVerified,
  firstName: kcUser.firstName,
  lastName: kcUser.lastName,
  enabled: kcUser.enabled,
  attributes: transformAttributes(kcUser.attributes),
  groups: kcUser.groups,
});

// Handle password migration
// Option A: Import bcrypt hashes (if using bcrypt)
// Option B: Force password reset
// Option C: Lazy migration via Keycloak during transition

Phase 5: Update Applications

Update OIDC configuration in your applications:

Before (Keycloak):

const oidcConfig = {
  issuer: 'https://keycloak.example.com/realms/your-realm',
  authorizationURL: 'https://keycloak.example.com/realms/your-realm/protocol/openid-connect/auth',
  tokenURL: 'https://keycloak.example.com/realms/your-realm/protocol/openid-connect/token',
  clientID: 'your-client',
  clientSecret: 'your-secret',
};

After (TitaniumVault):

const oidcConfig = {
  issuer: 'https://your-org.titanium-vault.com',
  authorizationURL: 'https://your-org.titanium-vault.com/oauth/authorize',
  tokenURL: 'https://your-org.titanium-vault.com/oauth/token',
  clientID: 'your-new-client-id',
  clientSecret: 'your-new-secret',
};

Phase 6: Migration Validation

Test checklist:

  • [ ] All clients can authenticate
  • [ ] User login works (local users)
  • [ ] LDAP/AD federation works
  • [ ] Social login works
  • [ ] SAML applications work
  • [ ] MFA enrollment and verification
  • [ ] Password reset flow
  • [ ] User self-service features
  • [ ] Admin operations
  • [ ] API access

Handling Keycloak-Specific Features

Custom Themes

Keycloak themes use FreeMarker templates. TitaniumVault uses:

  • CSS customization
  • Logo and color configuration
  • Custom HTML blocks for specific pages

Migration approach: Extract branding elements (logos, colors, copy) and apply via TitaniumVault's branding settings.

Custom SPIs

If you've built custom SPIs:

  1. User Storage SPI: Use TitaniumVault's user import or federation features
  2. Authenticator SPI: Implement via webhooks or contact support for custom flows
  3. Event Listener SPI: Use TitaniumVault's webhook system

Authentication Flows

Complex authentication flows need manual recreation:

  1. Document each step in your custom flow
  2. Map to TitaniumVault's authentication policies
  3. Use conditional access rules for complex logic
  4. Implement webhooks for custom logic

Decommissioning Keycloak

After successful migration:

  1. Keep Keycloak running read-only for 30 days

    • Catch any missed applications
    • Fallback for edge cases

  2. Monitor both systems

    • Track login attempts on old system
    • Investigate any Keycloak usage

  3. Final shutdown

    • Backup final state
    • Document the migration
    • Decommission infrastructure

Total Cost of Ownership Comparison

| Cost Factor | Self-Hosted Keycloak | TitaniumVault | |-------------|---------------------|---------------| | Infrastructure | $500-2000/mo | Included | | DevOps Time | 20-40 hrs/mo | 0 | | Security Patches | Your responsibility | Included | | High Availability | Complex setup | Included | | Support | Community only | Included | | Compliance Certs | DIY | Included |

Considering moving from self-hosted Keycloak? Start a free trial and we'll help you migrate. Our team has extensive Keycloak experience and can ensure a smooth transition.

Tags

KeycloakMigrationTitaniumVaultSelf-HostedOpen Source
Back to Blog