Migrating to Keycloak: Our Journey to Enhanced Security

As we continue building PixelUnion—your privacy-focused Google Photos alternative from Europe—we’re constantly working to improve security and user experience. Today, we want to share an important update about our identity provider migration and what it means for you.

Why We Need an Identity Provider

Our platform is built on Immich, an incredible open-source photo management solution. However, Immich is designed with a specific philosophy: it focuses on being the best photo management software, not on reinventing identity management.

Immich does not support two-factor authentication (2FA) or other advanced security features by design. This isn’t a flaw—it’s a deliberate architectural choice. The Immich team believes, and we wholeheartedly agree, that running an identity provider is complex work that should be handled by specialized software maintained by security professionals. This allows Immich to focus on what it does best: managing your photos and videos.

But as a SaaS platform serving thousands of users, we need advanced security features that Immich doesn’t provide:

Two-Factor Authentication (2FA): Protecting accounts with time-based one-time passwords (TOTP) from authenticator apps
Passkeys: Modern, passwordless authentication
Advanced user management: Inviting family and friends with proper account flows
Enterprise-grade security: Meeting the security standards our users expect

This is why we decided to implement our own identity provider.

Frequently Asked Questions

What does this migration mean for me?

For most users, the migration is seamless. Your account credentials remain the same, and you can continue using PixelUnion exactly as before. The main difference is that you now have access to enhanced security features like two-factor authentication.

When you log in, you’ll be redirected to our new Keycloak-based login system. Your username and password work exactly as they did before—no changes needed on your end.

Why is this migration necessary?

This migration is necessary because:

Security: Immich doesn’t support 2FA or advanced security features by design. We need these features to protect your accounts properly.
User experience: An external identity provider allows us to offer features like password recovery, account management, and secure user invitations.
Compliance: As a European service handling personal data, we need enterprise-grade identity management that meets regulatory requirements.
Future-proofing: A dedicated identity provider gives us the flexibility to add new security features as they become available.

We support Immich’s decision to focus on photo management rather than identity management. This separation of concerns is good software architecture, but it means we need to handle identity separately.

How do I enable two-factor authentication?

Now that we’ve migrated to Keycloak, you can enable two-factor authentication to add an extra layer of security to your account. Here’s how:

Go to the PixelUnion Account Security page
Log in with your username and password
In the Signing In section, find Two-Factor Authentication or Authenticator Application
Click Set up Authenticator Application
Scan the QR code with your authenticator app (such as Aegis Authenticator, 2FAS, Google Authenticator, Microsoft Authenticator, or Authy)
Enter the 6-digit code from your app to verify
Important: Save your backup codes in a secure location

For detailed step-by-step instructions, see our Two-Factor Authentication guide.

Why didn’t I need to reset my password?

Great question! You didn’t need to reset your password because we successfully migrated your password hashes from Immich to Keycloak.

Here’s how it works and why it’s safe:

How Password Hashing Works

When you create an account, your password is never stored in plain text. Instead, it’s processed through a cryptographic hash function (in this case, bcrypt2) that converts your password into a unique string of characters. This hash is a one-way function—you can’t reverse it to get the original password.

The Migration Process

Both Immich and Keycloak use the same password hashing algorithm: bcrypt2 (also known as bcrypt with version identifier $2b$ ). This means:

Your password hash from Immich is in a format that Keycloak understands
We can copy your hash directly from Immich’s database to Keycloak’s database
Keycloak can verify your password using the same hash without needing the original password

Why This Is Safe

No password exposure: We never see or handle your actual password—only the hash
Same security level: The hash format is identical, so there’s no security degradation
Industry standard: bcrypt2 is a well-established, secure hashing algorithm used by millions of applications
No plaintext storage: Your password was never stored in plaintext before, and it isn’t now

This migration approach is standard practice in the industry and is used by major platforms when transitioning between identity providers. It’s secure, seamless, and doesn’t require any action from you.

Will I notice any changes when logging in?

The login experience is very similar to before. You’ll still enter your username and password, but you’ll be redirected to our Keycloak-based login page. The URL will show login.pixelunion.eu instead of your instance domain. Once logged in, you’ll be seamlessly redirected back to your PixelUnion instance.

What if I have trouble logging in after the migration?

If you experience any issues logging in:

Double-check your credentials: Make sure you’re using the same username and password as before
Clear your browser cache: Sometimes cached login pages can cause issues
Try a different browser: This helps rule out browser-specific problems
Check for browser extensions: Some password managers or security extensions might interfere
Contact support: If none of the above works, reach out to our support team—we’re here to help!

Is my data safe during the migration?

Absolutely. The migration process:

Doesn’t affect your photos or videos: All your media remains untouched in your Immich instance
Only migrates authentication data: We only transfer account credentials (username and password hash)
Happens securely: The migration is performed using secure, encrypted connections
Is tested thoroughly: We’ve extensively tested the migration process before rolling it out

Your data privacy and security remain our top priorities throughout this process.

Do I need to update any apps or integrations?

Mobile apps: If you’re using the Immich mobile app, you may need to log out and log back in once after the migration. Your saved credentials should continue to work.

API keys: If you’re using API keys for integrations, these remain unchanged and continue to work as before.

Third-party integrations: Any integrations using OAuth or OpenID Connect will automatically work with the new Keycloak system, as it uses the same industry-standard protocols.

Active sessions may be logged out during the migration. This is a security measure to ensure all sessions are properly authenticated with the new system. Simply log in again with your existing credentials—no password reset needed.

If you’ve shared your account credentials with family or friends, they’ll need to use the new login system, but their access remains the same. We recommend that each person has their own account for better security. With Keycloak, we can now support proper multi-user setups with individual accounts and permissions.

Is 2FA mandatory, or can I opt out?

Two-factor authentication is optional but highly recommended. We strongly encourage all users to enable 2FA for enhanced account security, but it’s not required. You can enable it at any time from your Account Security page.

I have multiple PixelUnion instances, and my password isn’t working. What should I do?

If you have multiple PixelUnion instances and find that your password isn’t working after the migration, this is likely because we can only migrate each user once. If you had accounts on multiple instances, the password from one of your installations was migrated, but not necessarily the one you’re trying to access.

Don’t worry—this is easy to fix! You can reset your password directly from the login page:

Go to the PixelUnion login page
Click Forgot Password? or Reset Password
Enter your email address
Check your email for the password reset link
Follow the instructions to set a new password

If you need any assistance or have trouble resetting your password, please contact our support team. We’re here to help!

Our Journey: From Authentik to Keycloak

In our previous blog post, we explained why we chose Authentik as our identity provider. Authentik is a great open-source solution that ticked many boxes: it’s European-friendly, supports industry-standard protocols, and provides the security features we needed.

However, after spending significant time implementing Authentik, we discovered that it wasn’t the right fit for our specific needs. While Authentik is excellent software, we encountered challenges that made us reconsider our choice. After careful evaluation, we made the decision to switch to Keycloak.

Keycloak is a mature, battle-tested identity provider that’s been used by organizations worldwide for years. It offers:

Proven reliability: Used by major enterprises and organizations
Comprehensive documentation: Extensive resources and community support
Better fit for our architecture: Aligns more closely with our technical requirements
Robust feature set: All the security features we need, plus room to grow

This switch required additional development time, but we’re confident it was the right decision for the long-term stability and security of PixelUnion.

What’s Next?

We’re continuing to enhance our identity provider setup and add new security features. If you have any questions or concerns about the migration, please contact our support team. We’re here to help!

Thank you for being part of the PixelUnion community. Your security and privacy remain our top priorities.