From 4aadff4d8f1240d95a5b17a02b5fb8e5edc089f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Mon, 19 Oct 2020 19:05:17 +0300 Subject: [PATCH] revise the IDS4 upgrade guide. --- docs/en/Migration-Guides/Abp-4_0.md | 54 ++++++++++++++++++ .../IdentityServer-from-v3-to-v4.md | 55 ------------------- 2 files changed, 54 insertions(+), 55 deletions(-) create mode 100644 docs/en/Migration-Guides/Abp-4_0.md delete mode 100644 docs/en/Migration-Guides/IdentityServer-from-v3-to-v4.md diff --git a/docs/en/Migration-Guides/Abp-4_0.md b/docs/en/Migration-Guides/Abp-4_0.md new file mode 100644 index 0000000000..a94b3027a6 --- /dev/null +++ b/docs/en/Migration-Guides/Abp-4_0.md @@ -0,0 +1,54 @@ +# ABP Framework 3.3 to 4.0 Migration Guide + +## Identity Server Changes + +ABP Framework upgrades the [IdentityServer4](https://www.nuget.org/packages/IdentityServer4) library from 3.x to 4.x with the ABP Framework version 4.0. IdentityServer 4.x has a lot of changes, some of them are **breaking changes in the data structure**. + +### Database Changes + +**So, if you are upgrading from 3.x, then there are some change should be done in your database.** + +#### ApiScope + +As the **most important breaking change**, Identity Server 4.x places the `ApiScope` as an independent aggregate root. Previously it was a part of the to `ApiResource` aggregate. This requires manual operation. See the *Database Migration* section. + +Also, added `Enabled(string)` and `Description(bool,true)` properties. + +#### Client + +* Added `RequireRequestObject (bool)` and `AllowedIdentityTokenSigningAlgorithms (string)` properties. +* Changed default value of `RequireConsent` from `true` to `false`. +* Changed default value of `RequirePkce` from `false` to `true`. + +#### DeviceFlowCodes + +* Added `SessionId (string)` and `Description (string)` properties. + +#### PersistedGrant + +* Added `SessionId (string)` and `ShowInDiscoveryDocument (bool, default: true)` properties + +#### ApiResource + +* Added `AllowedAccessTokenSigningAlgorithms (string)` and `Description (string)` and `ConsumedTime (DateTime?)` properties + +#### ApiScope + +* Before it was a property of `ApiResource`, now it becomes an independent aggregate root. + +## Migrating the Database + +> Attention: **Please backup your database** before the migration! + +If you are using **Entity Framework Core**, you need to add a new database migration, using the `Add-Migration` command, and apply changes to the database. Please **review the migration** script to understand if it effects your existing data. Otherwise, you may **loose some of your configuration**. + +If you haven't customize the `IdentityServerDataSeedContributor` and haven't customized the initial data inside the `IdentityServer*` tables; + +1. Update `IdentityServerDataSeedContributor` class by comparing to [the latest code](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Domain/IdentityServer/IdentityServerDataSeedContributor.cs). You probably only need to add the `CreateApiScopesAsync` method and the code related to it. +2. Then you can simply clear all the **table data** in these tables then execute the `DbMigrator` application again to fill it with the new configuration. + +If you've customize your IdentityServer configuration in the database or in the seed data, you should understand the changes and upgrade your code/data accordingly. + +### Related Resources +* https://leastprivilege.com/2020/06/19/announcing-identityserver4-v4-0/ +* https://github.com/IdentityServer/IdentityServer4/issues/4592 \ No newline at end of file diff --git a/docs/en/Migration-Guides/IdentityServer-from-v3-to-v4.md b/docs/en/Migration-Guides/IdentityServer-from-v3-to-v4.md deleted file mode 100644 index 874c7b7a01..0000000000 --- a/docs/en/Migration-Guides/IdentityServer-from-v3-to-v4.md +++ /dev/null @@ -1,55 +0,0 @@ -# Migration Guide for the Abp Identity Server from the v3 to the v4 - -Identity Server released the v4 version in June this year. This version brings a lot of features, enhancements and bug fixes. Unfortunately, it is also breaking changes. - -I saw that it released several bug patches in a short time, so we did not upgrade to v4 in the first time. - -We are now upgraded abp to net 5, we think it is time to upgrade Identity Server to v4. - -There are a lot of code changes for the abp team, but fortunately for developers, you don't need to do that, just like the changes we made in the application template. - -Breaking changes to the database are always tricky. In Identity Server v4 it uses `ApiScope` as an independent aggregate root. Previously it belonged to `ApiResource`. Some entities have also been changed(adding new properties, changing default values, etc.). - -## The following are the specific changes: - -`Client`: -* Added `RequireRequestObject(bool)` and `AllowedIdentityTokenSigningAlgorithms(string)` properties. -* Change `RequireConsent` from `true` to `false`. -* Change `RequirePkce` from `false` to `true`. - -`DeviceFlowCodes`: -* Added `SessionId(string)` and `Description(string)` properties. - -`PersistedGrant`: -* Added `SessionId(string)` and `ShowInDiscoveryDocument(bool,true)` properties - -`ApiResource`: -* Added `AllowedAccessTokenSigningAlgorithms(string)` and `Description(string)` and `ConsumedTime(DateTime?)` properties - -`ApiScope`: -* Before it was a property of `ApiResource`, now it becomes an independent aggregate root. -* Added `Enabled(string)` and `Description(bool,true)` properties - -Before we used `Dictionary` as aggregate root's `Properties`, now we use independent classes such as `ApiResourceProperty`, `ApiScopeProperty`, `IdentityResourceProperty`. - -These are the changes you need to pay attention to. - -## How to migrate to Identity Server v4? - -> Please backup your database before migration!!! - -* If you are using EF Core, you need to add a new migration for Identity Server v4 changes. -* Update the `IdentityServerDataSeedContributor` class in your project according to [the latest code](https://github.com/abpframework/abp/blob/dev/templates/app/aspnet-core/src/MyCompanyName.MyProjectName.Domain/IdentityServer/IdentityServerDataSeedContributor.cs). - -If you have been using hard coding configuration to initialize the identity server just like we do in the application template project, a simple migration method is `clear all the tables related to the identity server in the database, and then execute the `DbMigrator` application. - -If you customize the `IdentityServerDataSeedContributor` or the entities mentioned above, you may need to update your code according to the actual situation. You have already understood all the changes, I think it will not be too complicated. - -If you have made some advanced changes to the Identity server, please check [the commit](https://github.com/abpframework/abp/commit/e118346f12b2fb146ab67f2655148916ba4a4518) for all our changes. - -That's all. - -## Related resources: -https://leastprivilege.com/2020/06/19/announcing-identityserver4-v4-0/ - -https://github.com/IdentityServer/IdentityServer4/issues/4592 \ No newline at end of file