lsm/openiddict-documentation
1
0
Fork 0
mirror of https://gitee.com/dcren/openiddict-documentation.git synced 2025-07-15 23:13:34 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update the migration guide to clarify the listed versions

Browse Source
This commit is contained in:
Kévin Chalet 2021-01-13 06:29:13 +01:00
parent adb445dcde
commit 0cdf933ab2
2 changed files with 50 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
guide/getting-started.md
View File

@ -118,7 +118,7 @@ If you don't want to start from one of the recommended samples, you'll need to:
``` ```
> [!WARNING] > [!WARNING]
> Important: if you change the default entity primary key (e.g. to `int` or `Guid` instead of `string`), make sure you use the `options.ReplaceDefaultEntities<TKey>()` > If you change the default entity primary key (e.g. to `int` or `Guid` instead of `string`), make sure you use the `options.ReplaceDefaultEntities<TKey>()`
> core extension accepting a `TKey` generic argument and use the generic `options.UseOpenIddict<TKey>()` overload to configure EF Core to use the specified type: > core extension accepting a `TKey` generic argument and use the generic `options.UseOpenIddict<TKey>()` overload to configure EF Core to use the specified type:
> >
> ```csharp > ```csharp

67
guide/migration.md
View File

@ -1,6 +1,36 @@
# Migrate to OpenIddict RC3 # Migrate to OpenIddict 1.0/2.0
## What's new in OpenIddict RC3? ## What's new?
The announcement listing the changes introduced in this milestone can be found [here](https://kevinchalet.com/2018/11/01/openiddict-1-0-and-2-0-general-availability/).
## Update your packages references
For that, simply update your `.csproj` file to point to the newest OpenIddict packages:
### ASP.NET Core 1.x
```xml
<ItemGroup>
<PackageReference Include="OpenIddict" Version="1.0.0" />
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="1.0.0" />
</ItemGroup>
```
### ASP.NET Core 2.x
```xml
<ItemGroup>
<PackageReference Include="OpenIddict" Version="2.0.0" />
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0" />
</ItemGroup>
```
No additional change should be required for basic scenarios.
# Migrate to OpenIddict 1.0/2.0 rc3
## What's new?
The announcement listing the changes introduced in this milestone can be found [here](https://kevinchalet.com/2018/06/20/openiddict-rc3-is-out/). The announcement listing the changes introduced in this milestone can be found [here](https://kevinchalet.com/2018/06/20/openiddict-rc3-is-out/).
@ -27,18 +57,18 @@ For that, simply update your `.csproj` file to point to the newest OpenIddict pa
``` ```
> [!TIP] > [!TIP]
> Note: if you have an explicit reference to `AspNet.Security.OAuth.Validation` or `OpenIddict.Mvc`, > If you have an explicit reference to `AspNet.Security.OAuth.Validation` or `OpenIddict.Mvc`,
> you can safely remove these dependencies: they are now transitively referenced by the `OpenIddict` metapackage. > you can safely remove these dependencies: they are now transitively referenced by the `OpenIddict` metapackage.
> [!IMPORTANT] > [!IMPORTANT]
> Note: if your application references `OpenIddict.Models` or `OpenIddict.Stores`, you MUST remove them as these packages are no longer used in RC3. > If your application references `OpenIddict.Models` or `OpenIddict.Stores`, you MUST remove them as these packages are no longer used in rc3.
## Use the new OpenIddict services registration APIs ## Use the new OpenIddict services registration APIs
To offer a better user experience, the registrations APIs exposed by OpenIddict have been reworked. Updating your code should be quite straightforward: To offer a better user experience, the registrations APIs exposed by OpenIddict have been reworked. Updating your code should be quite straightforward:
```csharp ```csharp
// In OpenIddict RC2, all the options used to be grouped. // In OpenIddict rc2, all the options used to be grouped.
services.AddOpenIddict(options => services.AddOpenIddict(options =>
{ {
options.AddEntityFrameworkCoreStores<ApplicationDbContext>(); options.AddEntityFrameworkCoreStores<ApplicationDbContext>();
@ -69,7 +99,7 @@ services.AddOpenIddict(options =>
``` ```
```csharp ```csharp
// In OpenIddict RC3, the options are now split into 3 categories: // In OpenIddict rc3, the options are now split into 3 categories:
// the core services, the server services and the validation services. // the core services, the server services and the validation services.
services.AddOpenIddict() services.AddOpenIddict()
.AddCore(options => .AddCore(options =>
@ -128,14 +158,14 @@ services.AddOpenIddict()
``` ```
> [!TIP] > [!TIP]
> Note: the OpenIddict validation handler lives in the `OpenIddict.Validation` package, which is referenced by the `OpenIddict` metapackage. > The OpenIddict validation handler lives in the `OpenIddict.Validation` package, which is referenced by the `OpenIddict` metapackage.
> You don't have to explicitly add a new `PackageReference` in your `.csproj` file to be able to use it. > You don't have to explicitly add a new `PackageReference` in your `.csproj` file to be able to use it.
## If necessary, create new application entries ## If necessary, create new application entries
OpenIddict now rejects unauthenticated token/revocation requests by default. OpenIddict now rejects unauthenticated token/revocation requests by default.
If, after migrating to RC3, you see errors similar to this one: If, after migrating to rc3, you see errors similar to this one:
> **invalid_request** : The mandatory 'client_id' parameter is missing. > **invalid_request** : The mandatory 'client_id' parameter is missing.
@ -172,9 +202,9 @@ services.AddOpenIddict()
## If necessary, register the scopes used by your clients ## If necessary, register the scopes used by your clients
Starting with RC3, OpenIddict will reject unrecognized scopes by default. Starting with rc3, OpenIddict will reject unrecognized scopes by default.
If, after migrating to RC3, you see errors similar to this one: If, after migrating to rc3, you see errors similar to this one:
> **invalid_scope** : The specified 'scope' parameter is not valid. > **invalid_scope** : The specified 'scope' parameter is not valid.
@ -204,7 +234,7 @@ services.AddOpenIddict()
## If necessary, adjust the permissions granted to your clients ## If necessary, adjust the permissions granted to your clients
**Starting with RC3, permissions are no longer optional nor implicit**: **Starting with rc3, permissions are no longer optional nor implicit**:
if you don't explicitly grant an application the necessary permissions, it will be blocked by OpenIddict. if you don't explicitly grant an application the necessary permissions, it will be blocked by OpenIddict.
To attach permissions to an application, use `OpenIddictApplicationManager`: To attach permissions to an application, use `OpenIddictApplicationManager`:
@ -248,23 +278,24 @@ services.AddOpenIddict()
``` ```
--------------------------- ---------------------------
# Migrate to OpenIddict RC2 # Migrate to OpenIddict 1.0/2.0 rc2
## What's new in OpenIddict RC2? ## What's new?
The full list of changes can be found [here](https://github.com/openiddict/openiddict-core/milestone/8?closed=1). It includes **bug fixes** (including a bug fix in the refresh token handling) The full list of changes can be found [here](https://github.com/openiddict/openiddict-core/milestone/8?closed=1). It includes **bug fixes** (including a bug fix in the refresh token handling)
and new features like **application permissions**, that allow limiting the OpenID Connect features (endpoints and flows) an application is able to use. and new features like **application permissions**, that allow limiting the OpenID Connect features (endpoints and flows) an application is able to use.
**Migrating to OpenIddict RC2 (`1.0.0-rc2-final` and `2.0.0-rc2-final`) requires making changes in your database**: existing properties have been reworked **Migrating to OpenIddict rc2 (`1.0.0-rc2-final` and `2.0.0-rc2-final`) requires making changes in your database**: existing properties have been reworked
(e.g [to work around a MySQL limitation](https://github.com/openiddict/openiddict-core/issues/497)) and new ones have been added to support the new features. (e.g [to work around a MySQL limitation](https://github.com/openiddict/openiddict-core/issues/497)) and new ones have been added to support the new features.
This procedure is quite easy and only requires a few minutes. This procedure is quite easy and only requires a few minutes.
> Note: this guide assumes your application uses the OpenIddict Entity Framework Core 2.x stores. If you use a custom store, changes will have to be made manually. > [!TIP]
A list of added/updated/renamed columns is available at the end of this guide. > This guide assumes your application uses the OpenIddict Entity Framework Core 2.x stores. If you use a custom store, changes will have to be made manually.
> A list of added/updated/renamed columns is available at the end of this guide.
## Ensure migrations are correctly enabled for your project ## Ensure migrations are correctly enabled for your project
**Before migrating to OpenIddict RC2, make sure migrations are already enabled for your application**. If you have a `Migrations` **Before migrating to OpenIddict rc2, make sure migrations are already enabled for your application**. If you have a `Migrations`
folder in your application root folder and an `__EFMigrationsHistory` table in your database, you're good to go. folder in your application root folder and an `__EFMigrationsHistory` table in your database, you're good to go.
If you don't have these Entity Framework Core artifacts, migrations are likely not enabled. To fix that, add the following entries in your `.csproj`: If you don't have these Entity Framework Core artifacts, migrations are likely not enabled. To fix that, add the following entries in your `.csproj`:
@ -410,7 +441,7 @@ ticket.SetResources("tracking_api", "marketing_api");
## Optionally, update your code to grant applications the minimum required permissions ## Optionally, update your code to grant applications the minimum required permissions
Starting with RC2, OpenIddict includes an optional feature codenamed "app permissions" that allows Starting with rc2, OpenIddict includes an optional feature codenamed "app permissions" that allows
controlling and limiting the OAuth2/OpenID Connect features a client application is able to use. controlling and limiting the OAuth2/OpenID Connect features a client application is able to use.
To learn more about this feature, read the [Application permissions documentation](../configuration/application-permissions.md). To learn more about this feature, read the [Application permissions documentation](../configuration/application-permissions.md).