Migrate your IdentityServer Solution to use AdminUI

Learn how to migrate your existing IdentityServer solution using our 2 easy-to-use migration scripts.

Out of the box, AdminUI doesn't support existing implementations of IdentityServer4 and ASP.NET Core Identity. Before you can run AdminUI, you will need to make both code changes and schema migrations. These code changes schema migrations are detailed below and allow AdminUI to handle migrations so that you don't have to. This migration is not a destructive operation; any existing IdentityServer functionality will continue to work. Migrations need to happen since AdminUI uses databases that extend the ASP.NET Core Identity and IdentityServer schemas.

Updating Your Existing Solution

There are several options for updating your existing IdentityServer solution. You can either manually migrate your database schema or let our migration script do the work for you. In this article, we will look at both options.

Manually Migrate the Database Schemas

Manual migration entails running the AdminUI on an empty database, comparing the schema against your existing database(s), and then manually making amendments to both schemas. This process is error-prone and time-consuming as you may need to continuously fix your script if not written correctly alongside repeatedly running migrations and restoring backups to test the manual migrations.

Each schema would have to be updated to match the schema that AdminUI generates. This includes tables related to EntityFramework migrations.

Finally, your IdentityServer solution will need code updates to the ASP.NET Identity registrations; these are detailed in our documentation.

Use the Migration Scripts Provided

Alternatively, to make the move to AdminUI, you can use the scripts below to carry out the start of the migrations. These scripts will create tables that will help AdminUI extend the functionality of IdentityServer. After running the IdentityServer schema migration scripts, you will then be able to run the existing AdminUI migrations.

Finally, a code update will need to be made in your IdentityServer solution to your ASP.NET Identity registrations if you want it to take advantage of AdminUI features such as soft deletion and lockout.

Before running the migrations, make sure to backup your database(s). The scripts provided both use transactions to ensure no updates occur if an error arises, but there is no rollback script provided post-update.

Running the ASP.NET Identity Migration Script

The ASP.NET Identity migration script can be found on the Rock Solid Knowledge GitHub. You can run this script using SSMS (SQLServer Management Studio).

The script will start by creating a new table using ClaimType values from the AspNetUserClaims table. All records are required to have a ClaimType value for the script to run.

IF((SELECT COUNT(*) FROM [dbo].[AspNetUserClaims] WHERE ClaimType IS NULL) > 0) RAISERROR('All AspNetUserClaims must have a ClaimType value', 16, 1)

A new table called AspNetClaimTypes is then created and distinct ClaimType values are inserted from the AspNetUserClaims table.

WITH CTE AS (SELECT DISTINCT ClaimType FROM AspNetUserClaims)
INSERT INTO [dbo].[AspNetClaimTypes]
    (Id,      ConcurrencyStamp, Name,        NormalizedName,   Required, Reserved, ValueType)
SELECT
     NEWID(), NEWID(),          ClaimType,   UPPER(ClaimType), 0,        0,        0
FROM CTE

At the end, the script will attempt to insert the EntityFramework migration records. See below for more detail.

If both the IdentityServer and ASP.NET Core Identity schema exist within the same database. We highly recommend that you backup your database again before running the IdentityServer4 migration script.

Running the IdentityServer4 Migration Script

The IdentityServer4 migration script can be found on the Rock Solid Knowledge GitHub. You can again run this script using SSMS.

The only notable part of this script is that at the end, the script will attempt to insert EntityFramework migrations records. See below for more detail.

Creating __EFMigrationHistory Record (Required)

At the end of both scripts, there is a check for the existence of the __EFMigrationsHistory table. If it does not exist, it will be created. Afterwards, the history of the migration will be added to the table. It is required that _EFMigrationHistory record is added to the _EFMigrationsHistory table.

IF (NOT EXISTS (SELECT *
                FROM INFORMATION_SCHEMA.TABLES
                WHERE TABLE_SCHEMA = 'dbo'
                AND  TABLE_NAME = '__EFMigrationsHistory'))
BEGIN
    ...
END

INSERT INTO [dbo].[__EFMigrationsHistory]
VALUES ('20171026080706_InitialSqlServerIdentityDbMigration', '2.1.4-rtm-31024')

Running the Final Migrations

By navigating to your AdminUI install directory and locating the IdentityExpress.Manager.Api.dll you can you run the final migrations using the following command.

dotnet IdentityExpress.Manager.Api.dll -migrate All

Alternatively, you can run specific migrations. More information on this can be found on our documentation.

Updating your ASP.NET Identity Registrations

To use some additional features from AdminUI, such as soft deletion and account locking, you will need to make some code changes that can be found in our documentation.

Finishing Up

You should now be able to run AdminUI against your database(s) with your existing clients and users. Any future releases of AdminUI will be able to migrate your database, and you can carry on getting updates and brand new features.

If you run into any issues with migrating your IdentitySchema, please email us via [email protected] or you can comment below.