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 above.
5. Monitor; rollback = repoint to the untouched Duende deployment.

NDJSON user import

A second, independent import source in the same Authagonal.Migration package: a flat NDJSON file (one JSON object per line) instead of a live database connection, and users only, no clients, roles, scopes or federation config. Built for migrating a legacy app’s own user table (a hand-rolled ASP.NET Identity store, a Rails/Devise table exported to bcrypt, a Node app on scrypt, …) so people keep logging in with their old password while it is transparently rehashed to native PBKDF2 on their next successful login, the same lazy-rehash path the Duende importer above relies on.

Record schema

One JSON object per line. email is the only required field; every other field is optional. Unknown top-level fields fail that line (strict by default) unless --AllowUnknownFields true is passed.

Example file (5 lines):

{"email":"ada.lovelace@legacy.example.com","givenName":"Ada","familyName":"Lovelace","passwordHash":"$2b$12$KIXQ8N6Qe0m6b6b6b6b6bOQe0m6b6b6b6b6b6b6b6b6b6b6b6b6b6","roles":["admin"],"organizationId":"org-legacy-1","externalId":"42"}
{"email":"bob@legacy.example.com","emailVerified":true,"attributes":{"dept":"eng"},"createdAt":"2019-03-04T00:00:00Z"}
{"email":"carol@legacy.example.com","disabled":true,"phoneNumber":"+61400000000"}
{"email":"dave@legacy.example.com","username":"dave1998","displayName":"Dave K."}
{"email":"erin@legacy.example.com"}

CLI

dotnet run --project tools/Authagonal.Migration.Cli -- import-ndjson-users \
    --Input ./users.ndjson \
    --Target:ConnectionString "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;TableEndpoint=https://..." \
    --DryRun true \
    --OnDuplicate skip \
    --BatchSize 500 \
    --AllowUnknownFields false \
    --ContinueOnError false \
    --AllowPlaintextPii true

Same target (Azure Table Storage) and PII-plaintext gate as the Duende CLI above, this source writes AuthUser rows straight to Table Storage with no host-registered IFieldCipher/IIndexTokenizer, so it refuses to run unless --AllowPlaintextPii true confirms the target has neither configured (or you wire NdjsonUserImportEngine into the host’s own DI container instead, where those seams do resolve). Unlike the Duende CLI there is no --AllowPlaintextSecrets gate: this source never writes MFA TOTP seeds or OAuth client secrets, only user profile fields and a password hash stored verbatim.

Options

Summary output & exit codes

The report is printed as JSON: TotalLines, Imported, Updated, Skipped, Failed, and the first 20 Failures (LineNumber + Reason). Blank lines are not counted anywhere. Exit codes:

• 0: success (or --ContinueOnError true with one or more failed lines)
• 1: one or more lines failed to parse/validate, and --ContinueOnError was not set
• 2: the run aborted: --OnDuplicate fail hit an existing email, or a required option was missing

Idempotency

The default --OnDuplicate skip makes re-running with an unchanged file a no-op the second time: every line whose email already exists is counted as skipped and nothing is written. update is safe to re-run too (it always re-applies the same fields); fail is for a one-shot import that should never silently collide with existing accounts.

What is NOT imported

• Roles, scopes, OAuth clients, federation config. This source is users only: see the Duende importer above if you also need those.
• MFA credentials, external logins. Not part of the schema; add them through the standard MFA setup / SSO flows after import.