Migration overview

This guide is the sequence for migrating an existing app onto CSI Auth. It assumes the app currently authenticates users itself, or through a system CSI Auth is replacing. Work through the phases in order; each one is designed to be reversible until the cutover.

Before you start

Write down, for the app as it exists today:

• Where user records live, and how many there are
• How passwords are stored—including the hashing algorithm and parameters
• How sessions are represented and how long they last
• What authorization data exists, and where the decisions are made
• Which integrations depend on the current login

Phase 1: Inventory and design

• Map current user attributes onto the CSI Auth profile
• Decide which connection type each population belongs in
• Translate existing authorization into roles and permissions
• Identify anything with no equivalent, and decide what happens to it

Phase 2: Provision

• Request the client for each environment
• Confirm which connections the app needs
• Create the roles the app will check
• Register callback and logout URLs

See Registering an app and Connections.

Phase 3: Migrate users

Two approaches, and the choice usually depends on the password hashes.

Bulk import

Users are loaded ahead of the cutover. Passwords come across only if the existing hashes are in a supported format; otherwise every user has to reset.

Lazy migration

Users move at their next successful login, verified against the legacy store. The legacy store has to stay reachable for the length of the migration window, and users who never return are never migrated.

Phase 4: Integrate the app

• Replace the login and logout flows with the standard OIDC flow
• Validate tokens on every request rather than trusting a session cookie
• Read identity from token claims instead of from the local user table
• Enforce permissions from the token’s scopes

Phase 5: Test

• Every connection type the app supports
• First login for a migrated user, including the password reset path
• Session expiry and refresh
• Role changes taking effect on the next token
• Logout, including any downstream session

Phase 6: Cut over

1. Run in stage against production-like data
2. Agree the rollback trigger and who calls it
3. Cut over in a low-traffic window
4. Watch authentication failure rates and support volume
5. Keep the legacy path available but off until the rollback window closes

Phase 7: Decommission

• Remove the legacy authentication code
• Delete the legacy credential store to the retention policy
• Revoke credentials the old system held
• Update runbooks and on-call documentation

Common problems