identityserver4-migration

What this skill does

# Migrating from IdentityServer4 to Duende IdentityServer

> **Scope: IdentityServer4 only.** This skill covers migrating from **IdentityServer4** (v3.x and v4.x) to Duende IdentityServer. It does **not** cover migrating from **IdentityServer3** (the older Thinktecture/`IdentityServer3` NuGet package that ran on OWIN/Katana and .NET Framework). IdentityServer3 is a fundamentally different product with a different API surface, configuration model, and hosting stack. If you are on IdentityServer3, you must first port to IdentityServer4 on ASP.NET Core before using this guide.

## When to Use This Skill

- Planning a migration from IdentityServer4 to Duende IdentityServer — running the migration analysis tool
- Upgrading a project from IdentityServer4 (v3.x or v4.x) to Duende IdentityServer v8
- Replacing IdentityServer4 NuGet packages with Duende equivalents
- Updating `IdentityServer4.*` namespaces to `Duende.IdentityServer.*`
- Migrating EF Core database schemas from IdentityServer4 to Duende IdentityServer
- Upgrading the .NET target framework from `netcoreapp3.1` or `net5.0` to a current LTS version
- Resolving breaking API changes between IdentityServer4 and Duende IdentityServer
- Converting `Startup.cs`/`Program.cs` hosting patterns from Generic Host to minimal hosting
- Configuring the Duende IdentityServer license key after migration
- Determining the right Duende license edition based on client inventory (interactive vs. non-interactive)
- Preserving the issuer URI to maintain token and client trust continuity
- Migrating signing keys from IdentityServer4 developer signing credential to Duende automatic key management
- Verifying third-party authentication scheme compatibility with the new .NET version
- Updating UI templates (login, logout, consent) from IdentityServer4 Quickstart UI to Duende templates

## Core Principles

**Migration has two stages if starting from v3.x.** IdentityServer4 v3 → v4 introduced breaking changes in the `ApiResource`/`ApiScope` relationship (parent-child to many-to-many). If you are on v3, first migrate to v4 semantics, then migrate from v4 to Duende. If you are already on IdentityServer4 v4.x, you can go directly to Duende.

**Duende IdentityServer is the direct successor to IdentityServer4.** The API surface is intentionally similar — most code changes are namespace and package renames. Behavioral changes are minimal, but the database schema has new tables and columns for features like automatic key management, server-side sessions, DPoP, and PAR.

**The .NET target framework must be upgraded alongside the IdentityServer migration.** IdentityServer4 ran on `netcoreapp3.1` or `net5.0`. Duende IdentityServer v8 requires `net10.0`. You must follow Microsoft's ASP.NET Core migration guides for each major version jump.

**Database migrations require careful handling to avoid data loss.** The v3 → v4 schema change renames tables and restructures relationships. A naive EF Core migration will drop and recreate tables, losing data. Use the provided delta SQL scripts or manually craft migrations that preserve data.

**Licensing is required for production use.** Duende IdentityServer requires a valid license key for production. Without one, it runs in community/trial mode and logs a warning on startup.

Docs: https://docs.duendesoftware.com/identityserver/upgrades

---

## Migration Path Overview

```
IdentityServer4 v3.x or v4.x
    │
    ▼ (Step 0: Run Migration Analysis Tool against running instance)
    │
    ▼ (Stage 1: v3 → v4 API changes + DB migration — skip if already on v4)
IdentityServer4 v4.x
    │
    ▼ (Stage 2: packages + namespaces + .NET upgrade + DB migration)
Duende IdentityServer v8.x
```

If already on IdentityServer4 v4.x, skip directly to Stage 2.

---

## Step 0: Run the Migration Analysis Tool (Recommended)

Before making any code changes, run the **Migration Analysis Tool** against your running IdentityServer4 instance. This tool inspects your live configuration and produces a report with specific recommendations.

The tool is a single file, [`MigrationAnalysisController.cs`](https://docs.duendesoftware.com/identityserver/upgrades/identityserver4-upgrade-analysis/), that you drop into your existing IdentityServer4 project. It does not require additional NuGet packages.

### What the tool inspects

| Data Point | Why It Matters |
|------------|---------------|
| **.NET runtime version** | Flags if you need to upgrade to .NET 10 |
| **IdentityServer4 version** | Determines if Stage 1 (v3 → v4) is needed before proceeding |
| **Client inventory** | Counts interactive (authorization code) vs. non-interactive (client credentials) clients — this determines which [Duende license edition](https://duendesoftware.com/products/identityserver) you need |
| **Issuer URI** | Reports the configured `IssuerUri` — must be preserved in Duende to avoid breaking existing tokens and client trust relationships |
| **Signing credential store type** | Identifies custom signing stores that may need compatibility updates |
| **Signing credential key ID** | Records the current key ID for signing key migration planning |
| **Data protection application name** | Flags missing or path-based discriminators that will break after .NET upgrade |
| **Data protection repository type** | Warns if keys are stored ephemerally (lost on restart) instead of a persistent store |
| **Authentication schemes** | Lists all registered authentication handlers — third-party handlers (non-Microsoft, non-IdentityServer4) may need version updates for the new ASP.NET Core version |

### Usage

1. Download `MigrationAnalysisController.cs` and add it to your IdentityServer4 project
2. **Update the authorization check** in the `Index()` method — the default placeholder checks for username `"scott"` which you must replace with your own authorization logic
3. Build, run, and navigate to `/MigrationAnalysis` while authenticated
4. Review the report and use it to plan your migration

The tool loads clients from in-memory configuration or EF Core stores automatically. If you use a custom client store, you will need to modify the constructor to wire up your client retrieval.

> **Note:** Duende also offers a [free IdentityServer4 upgrade assessment](https://duendesoftware.com) to walk through your upgrade path.

---

## Stage 1: IdentityServer4 v3.x → v4.x

Skip this section if you are already on IdentityServer4 v4.x.

### Step 1.1: Update NuGet Packages to v4

```xml
<!-- Old (v3) -->
<PackageReference Include="IdentityServer4" Version="3.1.4" />
<PackageReference Include="IdentityServer4.EntityFramework" Version="3.1.4" />
<PackageReference Include="IdentityServer4.AspNetIdentity" Version="3.1.4" />

<!-- New (v4) -->
<PackageReference Include="IdentityServer4" Version="4.1.2" />
<PackageReference Include="IdentityServer4.EntityFramework" Version="4.1.2" />
<PackageReference Include="IdentityServer4.AspNetIdentity" Version="4.1.2" />
```

### Step 1.2: Register API Scopes Separately

In v3, `ApiScope` was a child of `ApiResource`. In v4, scopes are independent top-level objects with a many-to-many relationship to API resources. You must register them separately:

```csharp
// v3: Scopes nested inside ApiResource
new ApiResource("api1", "My API")
{
    Scopes = { new Scope("api1.read"), new Scope("api1.write") }
}

// v4: Scopes are independent; ApiResource references scope names
public static IEnumerable<ApiScope> ApiScopes => new[]
{
    new ApiScope("api1.read", "Read access to API 1"),
    new ApiScope("api1.write", "Write access to API 1")
};

public static IEnumerable<ApiResource> ApiResources => new[]
{
    new ApiResource("api1", "My API")
    {
        Scopes = { "api1.read", "api1.write" } // string references, not Scope objects
    }
};

// Register both:
services.AddIdentityServer()
    .AddInMemoryApiScopes(Config.ApiScopes)       // NEW in v4
    .AddInMemoryApiResources(Config.ApiResources)
    .AddInMemoryClients(Config.Clients);
```

##