Migrating IdentityServer and ASP.NET Identity Core to AdminUI
If you have an existing IdentityServer or ASP.NET Identity Core setup then you will need to run script based migrations on their respective databases before being able to apply the AdminUI migrations. The scripts are only available for SqlServer and would need to be modified to run for PostgreSql or MySql.
Before running the migrations scripts you will need to backup your databases as there is no rollback script available from this point.
To migrate your ASP.NET Identity Core schema to then be able to run further migrations you can use the script found here: Migration script.
This script should work with ASP.NET Identity Core 8.0, 7.0, 6.0, 5.0, and 3.1.
This requires you to have all AspNetUserClaims records to have a ClaimType value and will add columns and tables to your database. Once the script has finished running you can apply the Identity migration from the AdminUI Migrations section.
To migrate your IdentityServer schema to then be able to run further migrations you can use the script found here: Migration script.
Identity Server schema migration script will work for all versions of IdentityServer up to v7. If you are migrating to earlier versions of AdminUI and IdentityServer you may need to consult the below table for modifications you may need to make to the migration history section if you want to use the AdminUI migration tool when upgrading to future versions.
| Version | Support | Migration History | | v4 | yes | Comment out migration history after '20200702080430_V3toV4SqlServerOperationalDbMigration' line 104 | | v5 | yes | Comment out migration history after '20210602110024_PersistedGrantConsumeTimeSqlServerOperationalMigration' line 108 | | v6 | yes | Comment out migration history after '20230620153729_Duende63ConfigurationUpdate' line 113 | | v7 | yes | -- Nothing to do -- |
Once the script has finished running you can apply the Configuration, ExtendedConfiguration and Operational migrations from the AdminUI Migrations section.
AdminUI Migrations
AdminUI comes with a tool to run all the necessary migrations. Alongside its own migrations, AdminUI can optionally run and maintain your IdentityServer4 and or Identity migrations, or you can handle them yourself. If you own SAML2P or WS-Fed, and wish to use its respective features within AdminUI, you will need to run their migrations.
By navigating to your AdminUI install directory and locating the IdentityExpress.Manager.UI.dll you can you run the dll using
dotnet IdentityExpress.Manager.UI.dll -migrate <migration-to-run>
AdminUI has a number of different migrations that need to be run, you can run one individually or choose to run them all at once.
The different migrations options are:
| Migration Type | Description |
|---|---|
| All | Runs all the migrations (Recommended for Demo users) |
| IdentityServerOnly | Runs AdminUI migrations along with the IdentityServer migrations (Migrations: Configuration, Operational, ExtendedConfiguration, Audit, Saml, WsFed and DataProtection) |
| IdentityOnly | Runs AdminUI migrations along with the Identity migrations (Migrations: Identity, ExtendedConfiguration, Audit, Saml, WsFed and DataProtection) |
| AdminUI | Runs only AdminUI migrations (Migrations: ExtendedConfiguration, Audit, Saml, WsFed and DataProtection) |
| Configuration | IdentityServer4 Configuration Migration |
| ExtendedConfiguration | AdminUI IdentityServer4 extension |
| Operational | IdentityServer4 Operational migration |
| Identity | ASP Identity Migration |
| Audit | RSK AdminUI Audit Migration |
| Saml | SAML2P Component migration |
| WsFed | Ws-Federation Component migration |
| DataProtection | DataProtection Key Migration (used if protecting cookies with a Database) |
A help function may be accessed by adding -help
Supported DbProviders
SqlServerMySqlPostgreSql
You may also specify a connection string and which database provider you are you using with -connectionstring and -dbprovider. The connection string must be valid and surrounded by quotes. If no connectionstring and dbprovider are given, the migration tool will look in AdminUI's appsettings.json for the values.
Migration Arguments
-dbProviderAllows you to override the configured dbProvider when running migrations, with the value provided following the argument-connectionStringAllows you to override the configured database connection string with a value provided following the argument-timeoutAllows you to customise the command timeout value used when running migrations
Schema Checker
AdminUI also comes with a tool that you can use to compare the expected IdentityServer database schema with your own IdentityServer schema.
By navigating to your AdminUI install directory and locating the IdentityExpress.Manager.UI.dll you can you run the dll using
dotnet IdentityExpress.Manager.UI.dll -schema <schema-to-check>
The different schema options are:
| Migration Type | Description |
|---|---|
| Configuration | IdentityServer4 Configuration Migration |
| Operational | IdentityServer4 Operational migration |
| Identity | ASP Identity Migration |
| Audit | RSK AdminUI Audit Migration |
| DataProtection | DataProtection Key Migration (used if protecting cookies with a Database) |
A help function may be accessed by adding -help
Supported DbProviders
SqlServerMySqlPostgreSql
After performing the schema check on the specified schema, a JSON encoded response object will be returned in the console. The object contains the following values: 'IsValid', 'Exists', 'ErrorMessages', 'SchemaType'.
If the response object's 'Exists' value is true, then the schema checker has identified that there are tables present in your database that relate to the schema it is checking.
The response object's 'IsValid' relates to if your database contains all the necessary tables and columns required for the schema you are checking. 'IsValid' is true when all tables and columns exist for a schema, and also when no tables and columns exist for a schema.
The 'ErrorMessages' section of the response object will contain information relating to any missing tables or columns in your database when compared to the schema you are checking.
You may also specify a connection string and which database provider you are you using with -connectionstring and -dbprovider. The connection string must be valid and surrounded by quotes. If no connectionstring and dbprovider are given, the migration tool will look in AdminUI's appsettings.json for the values.
Schema Check Arguments
-dbProviderAllows you to override the configured dbProvider when running migrations, with the value provided following the argument-connectionStringAllows you to override the configured database connection string with a value provided following the argument
Docker Migrations
If the container is not running and you would like to run migrations use the following command
docker run -e "DbProvider=<YourProvider>" -e "IdentityConnectionString=<YourConnectionString>" -e IdentityServerConnectionString="<YourConnectionString>" --entrypoint dotnet rocksolidknowledge/adminui IdentityExpress.Manager.UI.dll -migrate all
Note - The full list of configuration options is avaliable here
If the container is already running the steps to run migrations are as follows:
- Find the container ID by running the “docker container ps” command
- Once found, you can exec the command as follows:
docker exec <container-id> dotnet IdentityExpress.Manager.UI.dll -migrate all
Note - This will use the environment variables already passed into the container.
You will see the output of the migrations in your command line window.
TargetIdentityServer4
Make sure to back up your database before running any migrations against it as there is no way to easily revert changes once they have been applied.
The value of the TargetIdentityServer4 flag in AdminUI's configuration will determine what kind of database the AdminUI migrations will create/update.
If set to true, the AdminUI migration tool will perform IdentityServer4 migrations.
If set to false, the AdminUI migration tool will perform Duende IdentityServer migrations.
If you have performed the AdminUI migrations while targeting IdentityServer4 but wish to upgrade your database to target IdentityServer Duende, you can update the TargetIdentityServer4 flag to false and run the migrations again. The AdminUI migration tool will then update your database to be in line with the latest Duende IdentityServer schema.