Migration from Duende IdentityServer

The Authagonal.Migration package performs a one-time migration from Duende IdentityServer + SQL Server into Authagonal’s stores. The same engine is available two ways:

• Hosted runner (recommended) — a background service inside your Authagonal host that runs the migration once on deploy, gated on cluster leadership, without blocking startup.
• CLI — tools/Authagonal.Migration.Cli, for local/offline runs against a Table Storage target.

SqlClient lives only in this package, so hosts that don’t migrate never inherit it.

Hosted runner

Add it after AddAuthagonal (it depends on the stores, the secret provider, and cluster leadership):

builder.Services.AddAuthagonal(builder.Configuration, c => c.UseAzureStorage(blob, table));
builder.Services.AddAuthagonalDuendeMigration(builder.Configuration);

var app = builder.Build();
app.MapAuthagonalEndpoints();
app.MapAuthagonalDuendeMigration();   // GET /admin/migration/status

The second Map call is required and separate: this package references Authagonal.Server, so MapAuthagonalEndpoints cannot reach it. Without it GET /admin/migration/status answers 404 — indistinguishable from the IdentityAdmin policy refusing you — and the run logs a warning at startup saying so.

Configure via the Migration section:

{
  "Migration": {
    "Enabled": true,
    "DryRun": false,
    "Version": "1",
    "UsersMode": "CreateOnly",
    "MigrateClients": true,
    "MigrateRefreshTokens": false,
    "LeaseWaitMinutes": 10,
    "StartupDelaySeconds": 30,
    "Source": { "ConnectionString": "Server=...;Database=Identity;..." }
  }
}

The runner:

1. Waits StartupDelaySeconds (seed services finish first; startup is never blocked).
2. Skips if a Completed, non-DryRun marker already exists for Version.
3. Waits up to LeaseWaitMinutes to become cluster leader (only one pod runs the migration).
4. Writes a Started marker, runs the engine, then a Completed/Failed marker with the report.

Losing leadership mid-run cancels the engine; the new leader re-runs — safe because every pass is idempotent. Check progress at GET /admin/migration/status (gated by the IdentityAdmin policy).

CLI

docker run authagonal-migration \
  --Source:ConnectionString "Server=sql.example.com;Database=Identity;User Id=...;Password=...;" \
  --Target:ConnectionString "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;TableEndpoint=https://..." \
  --DryRun true --UsersMode CreateOnly

(No -- separator after the image name.) Or from source:

dotnet run --project tools/Authagonal.Migration.Cli -- \
  --Source:ConnectionString "Server=...;Database=...;" \
  --Target:ConnectionString "DefaultEndpointsProtocol=https;..." \
  --DryRun true

What gets migrated

Options

Idempotency & delta sweeps

Every pass is idempotent (skip-if-exists, deterministic MFA ids), so the migration is safe to re-run. Run it days ahead of cutover, then bump Version for a final delta sweep close to cutover to pick up users registered since. Existing records are skipped (or updated under Upsert), never duplicated.

What is NOT migrated

• Live refresh tokens, against stock Duende. Duende’s DefaultGrantStore never persists a refresh-token handle: PersistedGrants.Key holds base64(SHA-256(handle + ":" + grantType)), and the presented handle is hashed again on lookup. The handle is therefore not recoverable from the source database, and migrated rows would be permanently unredeemable — which is worse than not migrating, because the report counts them as created and the breakage only surfaces at the first token refresh after cutover. Plan the cutover around one re-login, or run a dual-read shim during the transition window. SourceGrantKeysAreUnhashed exists only for a fork whose grant store persists handles verbatim, and such a fork also owns translating PersistedGrants.Data from Duende’s RefreshToken shape into RefreshTokenData.
• SCIM tokens and groups, user provisions — no Duende equivalent; start empty.
• Signing keys — not automated. To keep existing tokens valid across cutover, export the RSA signing key from Duende and import it into the SigningKeys table close to cutover.

Cutover strategy

1. Deploy dark (Enabled=false).
2. Enabled=true, DryRun=true → restart → review the report at /admin/migration/status.
3. DryRun=false → restart → verify the marker is Completed + spot-check logins.
4. Bump Version for the final delta sweep, then repoint clients/BFFs to Authagonal. Expect one forced re-login — see below.
5. Monitor; rollback = repoint to the untouched Duende deployment.