Migrating Your IdentityServer4 v3 Database to IdentityServer4 v4

With the release of IdentityServer4 v4 comes new features, and with those features come model changes. To account for the model changes, your database needs to be updated.

To use the new version of IdentityServer4, you must update the database it is running against. This includes both the PersistedGrantDbContext (relating to device codes and persisted grants) and the ConfigurationDbContext (relating to clients, API resources, identity resources etc).

What Has Changed

Migrating to the new schema for the ConfigurationDbContext requires the following changes:

• New columns: add columns for Clients, ApiResources, ApiScopes, and ApiScopeClaims
• Remove columns: removing columns for ApiScopeClaims and ApiScopes
• Rename tables: rename ApiClaims, ApiProperties, ApiSecrets, IdentityClaims, and IdentityProperties
• Add tables: add two new tables - ApiResourceScopes and ApiResourceProperties

For more details on the new scope and resource modeling, please refer to the IdentityServer4 documentation.

Migrating to the new schema for the PersistedGrantDbContext requires the following changes:

• New columns: add columns for DeviceCodes and PersistedGrants

To make the transition easier, we have created several scripts that cover four different database types:

• MySQL
• MsSQL
• PostgreSQL
• SQLite

We'll tell you how to use these scripts from within your Entity Framework migrations to leverage the scripts alongside your existing migrations.

Migrating Your Database

Migration scripts can be found on GitHub for both the PersistedGrantDbContext and ConfigurationDbContext.

The readme for the repository details exactly what each script does, including any differences for each of the database types. It is strongly advised that you read through the readme to understand the outcome of the scripts.

Manual Migration

The scripts differ between whichever SQL database you have chosen to use. Once you have read the readme and are ready to run the scripts, make sure to backup your database(s) first. This will allow you to revert any changes if you are unhappy with the result of the migration.

To manually migrate, run the scripts however you choose against your database.

Including the Scripts as EntityFramework Migrations

Follow these steps for whichever DbContext you would like to migrate. In this example, we are migrating the ConfigurationDbContext.

Add a New Migration

Add a new migration to your project either through the .NET Core CLI or through the Package Manager Console in Visual Studio:

.NET Core CLI

dotnet ef migrations add V3toV4ConfigurationDbMigration -c ConfigurationDbContext

Visual Studio

Add-Migration V3toV4ConfigurationDbMigration -c ConfigurationDbContext

Add the Script to Your Project

Add the script associated to the DbContext that you are using to migrate to your project. It is suggested that you add the script to your project as an embedded resource. If you are using Visual Studio you can right click on the file, click Properties and set the Build Action to Embedded Resource.

You can also set the file to be an embedded resource through the csproj. Add an ItemGroup element that contains an EmbeddedResource element:

<ItemGroup>
    <EmbeddedResource Include="Migrations\Configuration\ConfigurationDbContext.sql" />    
</ItemGroup>

Run the SQL From Your Migration

To run the SQL, you will need to:

1. Pull the file out of the embedded resources
2. Read the contents of the file
3. Execute it

The name of the embedded resource will be the expected namespace of the file followed by the file name. In the case of the code below, the file sits within the IdentityExpress.Manager.Api.Migrations.Configuration namespace and the name of the file is ConfigurationDbContext.sql:

protected override void Up(MigrationBuilder migrationBuilder)
{
    var assembly = Assembly.GetExecutingAssembly();
    var resourceName = "IdentityExpress.Manager.Api.Migrations.Configuration.ConfigurationDbContext.sql"

    using Stream stream = assembly.GetManifestResourceStream(resourceName);
    using StreamReader sr = new StreamReader(stream);

    var sql = sr.ReadToEnd();

    migrationBuilder.Sql(sql);
}

Now when you run the migrations the database will be updated according to the .sql file loaded from within the assembly. Keep in mind that there is no Down migration method implemented. Backup your database before running the migrations so that you can revert any changes if you're unhappy with the result.

Finishing Up

You should now be able to run your IdentityServer4 solution using the latest version with all data retained.