|
| 1 | +--- |
| 2 | +title: "IdentityServer4 to Duende IdentityServer - Migration Analysis Tool" |
| 3 | +sidebar: |
| 4 | + order: 139 |
| 5 | + label: IdentityServer4 Migration Analysis |
| 6 | +--- |
| 7 | + |
| 8 | +import { Code } from "@astrojs/starlight/components"; |
| 9 | +import { Steps } from "@astrojs/starlight/components"; |
| 10 | +import { Tabs, TabItem } from "@astrojs/starlight/components"; |
| 11 | + |
| 12 | +To help assist in planning the [migration of an IdentityServer4 implementation to Duende IdentityServer](/identityserver/upgrades/identityserver4-to-duende-identityserver-v7.mdx), |
| 13 | +we provide a utility that [analyzes the current configuration of your current IdentityServer4](https://raw.githubusercontent.com/DuendeSoftware/docs.duendesoftware.com/refs/heads/main/src/content/docs/identityserver/upgrades/code/MigrationAnalysisController.cs). |
| 14 | +It inspects the running instance to provide specific recommendations and highlights potential compatibility issues during the upgrade and migration process. |
| 15 | + |
| 16 | +Note that the data provided is informative and should not be considered a complete migration plan. |
| 17 | + |
| 18 | +:::note |
| 19 | +We also offer a [free IdentityServer4 upgrade assessment](https://duendesoftware.com/upgrade-identityserver4) to walk you through your upgrade path. |
| 20 | +::: |
| 21 | + |
| 22 | +## Installation |
| 23 | + |
| 24 | +This Migration Analysis tool is provided as a single file, [`MigrationAnalysisController.cs`](https://raw.githubusercontent.com/DuendeSoftware/docs.duendesoftware.com/refs/heads/main/src/content/docs/identityserver/upgrades/code/MigrationAnalysisController.cs), which can be [downloaded](https://raw.githubusercontent.com/DuendeSoftware/docs.duendesoftware.com/refs/heads/main/src/content/docs/identityserver/upgrades/code/MigrationAnalysisController.cs) |
| 25 | +and added directly to any existing IdentityServer4 project. It does not require a separate library or complex installation process. |
| 26 | + |
| 27 | +The tool's code was deliberately kept rudimentary and compatible with earlier C# versions to ensure maximum compatibility with older projects. |
| 28 | + |
| 29 | +The controller is designed to inspect client configurations from: |
| 30 | +1. **In-Memory Clients** |
| 31 | +2. **Entity Framework Core** (standard `IdentityServer4.EntityFramework` stores) |
| 32 | + |
| 33 | +If your implementation uses a custom store for client configuration, you will need to modify the controller code (specifically in the constructor) to manually wire up the retrieval of your client data so it can be included in the analysis. |
| 34 | + |
| 35 | +:::danger[Security warning] |
| 36 | +To make use of the tool, you must update the authorization logic in the `Index()` method. Authorization is in place to ensure that only a user with the necessary claims can access the report for your environment. |
| 37 | +This is extremely important when deploying the migration analysis tool to your production environment. |
| 38 | + |
| 39 | +The default implementation contains a placeholder check that verifies if your username is `"scott"`: |
| 40 | +```csharp {3} |
| 41 | +// MigrationAnalysisController.cs |
| 42 | +// Verify user is allowed to access this page |
| 43 | +if (User.Identity == null || User.Identity.Name != "scott") |
| 44 | +{ |
| 45 | + return Unauthorized(); |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +You must replace this with checks for specific user characteristics (e.g., role, claim, or username) to ensure that only authorized users can access this sensitive information. |
| 50 | +::: |
| 51 | + |
| 52 | +## Usage |
| 53 | + |
| 54 | +To use the tool: |
| 55 | +1. Ensure the IdentityServer4 host is running. |
| 56 | +2. Navigate to the `/MigrationAnalysis` endpoint of your IdentityServer4 host in your browser (e.g., `https://localhost:5001/MigrationAnalysis`). |
| 57 | +3. Ensure you are logged in with a user that meets the security criteria defined in the `Index()` method. |
| 58 | + |
| 59 | +## Analysis Report |
| 60 | + |
| 61 | +The Analysis page provides a table with the following data points and recommendations: |
| 62 | + |
| 63 | +* **.NET Version:** Checks the runtime version and recommends upgrading to the latest LTS if needed. |
| 64 | +* **IdentityServer4 Version:** Verifies the current version. Migration to Duende IdentityServer typically requires being on IdentityServer4 v4.x first. |
| 65 | +* **Clients:** Provides information about interactive and non-interactive clients. This information is important for [determining the appropriate license edition for Duende IdentityServer](https://duendesoftware.com/products/identityserver/). |
| 66 | +* **Issuer URI:** Reports the current issuer URI, if configured. |
| 67 | +* **Signing Credential Store:** Identifies the type of store used for signing credentials and checks for compatibility. |
| 68 | +* **Signing Key:** Displays the current Key ID and links to documentation on migrating signing keys. |
| 69 | +* **Data Protection:** |
| 70 | + * **Application Name:** Checks if the Application Discriminator is set, which is crucial for key isolation. |
| 71 | + * **Repository Type:** Verifies where keys are stored (e.g., XML repository) to ensure they are persisted correctly in production. |
| 72 | +* **Authentication Schemes:** Lists all registered authentication handlers and highlights those that might not be compatible with newer ASP.NET Core versions. |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | +With this information, you can [start your IdentityServer4 to Duende IdentityServer migration](/identityserver/upgrades/identityserver4-to-duende-identityserver-v7.mdx) more informed. |
0 commit comments