Planning A ProAuth 2.x To 3.x Migration

Major version upgrades are easiest to underestimate when the application still looks familiar from the outside.

ProAuth v3 is one of those upgrades where the operating model matters as much as the feature list. The upcoming release keeps existing v1 API integrations functional, but it also changes database schema layout, authentication view customization, Helm chart secrets, Kubernetes resource names, CLI YAML files, and MFA terminology. That combination deserves a migration plan, not a late-night chart bump.

The practical starting point is simple: treat the move from ProAuth 2.x to 3.x as a planned maintenance upgrade with rehearsal, backups, and a short downtime window. The ProAuth migration guide is the source of truth for the detailed sequence. This post is the planning layer around it.

Start with the inventory

Before scheduling the upgrade window, build an inventory of the things that will move with the platform:

• the ProAuth database and every User Store database;
• the current ProAuth 2.x version in production;
• Helm values, pre-created Kubernetes Secrets, ConfigMaps, selectors, dashboards, ServiceMonitors, PodMonitors, NetworkPolicies, and deployment scripts;
• custom authentication views and custom assets;
• Management API and User Store API consumers;
• CLI data, label, and view-definition YAML files kept in configuration repositories;
• settings, imports, scripts, and documentation that still use TwoFactor or SecondFactor names.

That inventory decides how much work belongs before the maintenance window. The database bridge and Helm upgrade happen in the window. View rewrites, YAML conversion, API migration planning, secret preparation, and selector updates should not be discovered there.

flowchart TD
    inventory["Inventory: databases, Helm, APIs, views, YAML"]
    rehearse["Rehearse: bridge migration and Helm changes"]
    prepare["Prepare: backups, v3 Secrets, Fluid view plan"]
    window["Window: block writes, migrate database, upgrade Helm"]
    verify["Verify: login, Admin App, APIs, monitoring"]
    followup["Follow up: move API consumers to v2"]

    inventory --> rehearse --> prepare --> window --> verify --> followup

Plan for short downtime

The v2-to-v3 database migration is a planned downtime step. The migration guide says to update existing installations to the latest ProAuth 2.x release first, then migrate the SQL Server databases with the v2-to-v3 bridge command from the ProAuth 3.x CLI.

During the actual transition, stop ProAuth 2.x or otherwise block writes while the migration and Helm upgrade are running. That is not just operational caution. ProAuth 3.x moves ProAuth objects into the proauth schema and User Store objects into the userstore schema, applies v3 schema changes, rewrites legacy label content paths, and stamps the EF Core migration history so later upgrades continue through EF Core migrations.

The bridge command is designed to be rerunnable. If a User Store database fails, the error is logged and the migration continues with the next User Store database; after fixing the cause, you can run the command again for the remaining databases. That helps recovery from a partial migration attempt, but it is not a reason to skip rehearsal.

Backups are part of the upgrade, not a fallback idea

Take verified backups of the ProAuth database and every User Store database before running the bridge migration. “Verified” is the important word. The team should know where the backups are, which point in time they represent, and how to restore them if the window has to be rolled back.

For existing 2.x installations, the documented bridge path supports SQL Server source and SQL Server target databases only. A direct migration from SQL Server 2.x databases to PostgreSQL 3.x databases is not part of this upgrade path. PostgreSQL can be used for fresh ProAuth 3.x installations, or for a separate customer-specific data migration project, but it should not be silently folded into the 2.x-to-3.x upgrade window.

Move custom views from Razor to Fluid

Custom authentication views need their own workstream. ProAuth 3.x replaces Razor .cshtml custom views with Fluid/Liquid .liquid templates. Existing .cshtml view customizations are archived under a _legacy/ path during database deployment so they remain available for reference, but they are not rendered by the new Fluid view engine.

That has two planning consequences.

First, teams with customized login, verification, or account views should export and review those views before the upgrade. The rewrite is not a file-extension change. Razor model directives, injected services, hidden-field loops, and raw form markup need to become Fluid templates that use ProAuth building-block tags such as {% auth_form %}, {% auth_flow_id %}, input tags, validation tags, and localized title or link tags.

Second, styling assumptions may need attention. The migration guide notes that ProAuth 3.x replaces Bootstrap and jQuery patterns with Tailwind CSS, vanilla JavaScript, ProAuth component classes, and CSS custom properties. Custom assets are preserved, but Bootstrap-specific classes in old view customizations will not carry the design by themselves.

The Auth View Customization documentation is the right companion when rebuilding those templates.

Prepare Helm Secrets, names, and selectors

The Helm changes are easy to miss because they are infrastructure details rather than user-facing screens. They are still breaking changes.

ProAuth 3.x changes the Secret structure for both the ProAuth Core chart and the ProAuth Admin App chart. Installations that pre-create Kubernetes Secrets and enable externalSecrets need new v3 Secrets before upgrading the Helm release. The v3 chart does not read the old Secret group names or old lowercase keys; it expects direct .NET configuration environment variable names as Secret keys.

Resource names and labels also change. The charts standardize Kubernetes labels under the app.kubernetes.io/* model and rename several resources, jobs, service accounts, containers, and Dapr-related identifiers. Update scripts, dashboards, kubectl commands, NetworkPolicies, ServiceMonitors, PodMonitors, and custom wait logic that selected objects through labels such as app=proauth, app=proauthadminapp, or release=<release>.

This is good rehearsal material: render the v3 charts, compare the generated resources with your production automation, and update selectors before the maintenance window.

Keep v1 API working, but plan the v2 move

ProAuth 3.x introduces v2 Management and User Store APIs, but existing v1 API endpoints remain functional in ProAuth 3.x. That compatibility matters for the upgrade window: API consumers do not have to be rewritten before the database and Helm migration can complete.

Still, v1 is deprecated and planned for removal in a future major release. Treat the v3 upgrade as the point where you inventory API consumers and plan the move to v2. The v2 APIs use command-based write operations, type-safe patch operations, dedicated relationship endpoints, typed IDs in .NET clients, and the new RBAC permission model. That is a separate integration migration, not a surprise task for the infrastructure window.

Convert CLI YAML before reusing it

Configuration-as-code repositories need attention before they are used against ProAuth 3.x.

The CLI import format changes from v1 DTO-shaped YAML with tags such as !CustomerDto, !TenantDto, !UserDto, and !CustomViewFileImport to API-versioned resources with apiVersion, kind, metadata, spec, and explicit relationships. The migration guide documents CLI commands for data files, label files, and Admin UI view-definition files:

• proauthcli data migrate-yaml
• proauthcli label migrate-yaml
• proauthcli viewdefinition migrate-yaml

Run those conversions on the configuration repository before importing files into ProAuth 3.x. For the first data migration, keep the default conflict strategy so incompatible relationship declarations fail visibly. After conversion, review generated relationships blocks, especially relationships that may have been declared from both sides in older YAML files.

The same workstream should catch label path changes. The database bridge rewrites stored label content paths, and the CLI migration commands apply the corresponding mapping to files. Configuration repositories still need to be converted before reuse.

Update MFA names in v3-facing assets

ProAuth 3.x standardizes the old TwoFactor and SecondFactor naming to Mfa and MfaFactor. The bridge migration handles the database side for existing installations. Customer-maintained material still needs review: external settings, Helm values, appsettings overrides, import/export files, scripts, documentation, and v2 API consumers.

There is one important compatibility boundary. Management API v1 remains backward compatible, so existing v1 routes, DTOs, JSON properties, and generated v1 clients continue to use the legacy TwoFactor and SecondFactor names. The rename applies to v2 APIs, internal product configuration, modules, Admin UI resources, and new imports or exports.

Custom MFA views need extra care. The migration guide lists renamed MFA view routes and says custom view overrides at old MFA paths should be recreated at the new v3 paths with Fluid syntax.

A practical runbook shape

A good migration runbook should be boring by the time the real window starts.

1. Update the current environment to the latest ProAuth 2.x release.
2. Restore production-like database backups into a rehearsal environment.
3. Run the v2-to-v3 bridge migration with representative User Store databases.
4. Prepare v3 Helm values, external Secrets, ConfigMaps, and updated Kubernetes selectors.
5. Convert CLI YAML files and review generated relationships and label paths.
6. Export custom views, rebuild required overrides in Fluid, and test the affected login and MFA routes.
7. Inventory API consumers and decide which ones can stay on v1 temporarily while v2 migration work is scheduled.
8. During the production maintenance window, stop ProAuth 2.x or block writes, verify backups, run the bridge migration, deploy ProAuth 3.x with Helm, and validate the application and Admin App.
9. After the window, monitor login, API, Admin App, and database migration signals, then clean up archived legacy views when the Fluid replacements are complete.

The shape is deliberately conservative. ProAuth v3 brings a modernized platform baseline, but the safest migration is still the one that treats identity as production infrastructure: rehearse the irreversible parts, protect the data, name the downtime, and keep the follow-up work visible.

For the detailed migration sequence, mapping tables, and commands, start with the ProAuth migration guide. For the release-level scope and action-required summary, check the ProAuth 3.0.0 release notes.