Note
This documentation is a work-in-progress. To contribute, please visit https://github.com/openiddict/openiddict-documentation.
-Migrate to OpenIddict 1.0/2.0
+Migrate to OpenIddict 3.0
+What's new?
-The announcement listing the changes introduced in this milestone can be found here.
+The announcement listing the changes introduced in this milestone can be found here.
+Important
Migrating to OpenIddict 3.0 requires making changes to your database: existing properties have been reworked and new ones have been added to support the new features.
+Update your packages references
+For that, update your .csproj file to reference the OpenIddict.AspNetCore 3.x metapackage:
<ItemGroup>
+ <PackageReference Include="OpenIddict.AspNetCore" Version="3.0.3" />
+ <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="3.0.3" />
+</ItemGroup>
+Ensure your application doesn't reference legacy/unsupported packages
+As part of the AspNet.Security.OpenIdConnect.Server/OpenIddict merge, the ASOS packages and 2 OpenIddict packages have been marked as legacy +and are no longer supported. Make sure your application (or intermediate libraries) don't reference any of these packages:
+| Package name | +
|---|
| AspNet.Security.OpenIdConnect.Extensions | +
| AspNet.Security.OpenIdConnect.Primitives | +
| AspNet.Security.OpenIdConnect.Server | +
| + |
| Owin.Security.OpenIdConnect.Extensions | +
| Owin.Security.OpenIdConnect.Server | +
| + |
| AspNet.Security.OAuth.Introspection | +
| AspNet.Security.OAuth.Validation | +
| + |
| Owin.Security.OAuth.Introspection | +
| Owin.Security.OAuth.Validation | +
| + |
| OpenIddict.Models | +
| OpenIddict.Mvc | +
Update the references to the Entity Framework Core/Entity Framework 6/MongoDB models
+If your application references the OpenIddictApplication, OpenIddictAuthorization, OpenIddictScope or OpenIddictToken models, update these reference to use
+their new names: OpenIddict[provider name]Application, OpenIddict[provider name]Authorization, OpenIddict[provider name]Scope and OpenIddict[provider name]Token
+(e.g when using MongoDB: OpenIddictMongoDbApplication, OpenIddictMongoDbAuthorization, OpenIddictMongoDbScope and OpenIddictMongoDbToken).
Enable ASP.NET Core integration in the server and validation options
+With the base server and validation stacks being decoupled from ASP.NET Core, you now have to explicitly register the ASP.NET Core host in the server/validation options:
+services.AddOpenIddict()
+ .AddServer(options =>
+ {
+ options.UseAspNetCore();
+ })
+ .AddValidation(options =>
+ {
+ options.UseAspNetCore();
+ });
+Enable the authorization, logout and token endpoints pass-through mode
+Unless you're using OpenIddict's events model to handle authorization, logout and token requests, you'll need to enable +the pass-through mode for these endpoints, so that requests can reach your authorization controller as in the previous versions:
+services.AddOpenIddict()
+ .AddServer(options =>
+ {
+ options.UseAspNetCore()
+ .EnableAuthorizationEndpointPassthrough()
+ .EnableLogoutEndpointPassthrough()
+ .EnableTokenEndpointPassthrough();
+ });
+Enable ASP.NET Core Data Protection support to ensure existing tokens can still be validated
+For that, call options.UseDataProtection() in both the server and validation options:
services.AddOpenIddict()
+ .AddServer(options =>
+ {
+ options.UseDataProtection();
+ })
+ .AddValidation(options =>
+ {
+ options.UseDataProtection();
+ });
+Replace JSON.NET by System.Text.Json
+If you use JSON.NET to serialize or deserialize OpenIdConnectMessage, OpenIdConnectRequest or OpenIdConnectResponse instances,
+consider moving to System.Text.Json when migrating to OpenIddict 3.0, as 3.0 no longer includes a built-in JSON.NET JsonConverter for these types.
In most cases, this should be as simple as replacing JsonConvert.SerializeObject()/JsonConvert.DeserializeObject()
+by their System.Text.Json equivalent: JsonSerializer.Serialize()/JsonSerializer.Deserialize().
Add an apply migrations, if necessary
+If your application uses Entity Framework Core or Entity Framework 6, add a migration to react to the schema changes listed below and apply it.
+List of schema changes (for applications using custom stores)
+Updated properties
+| Table | +Column name | +Observations | +
|---|---|---|
| OpenIddictAuthorizations | +Subject | +The column is now nullable to support the device authorization flow. | +
| OpenIddictTokens | +CreationDate | +For broader database support, this column is a now a DateTime instance. |
+
| OpenIddictTokens | +ExpirationDate | +For broader database support, this column is a now a DateTime instance. |
+
| OpenIddictTokens | +Subject | +The column is now nullable to support the device authorization flow. | +
Added properties
+| Table | +Column name | +Type | +Nullable | +
|---|---|---|---|
| OpenIddictAuthorizations | +CreationDate | +DateTime | +Yes | +
| OpenIddictTokens | +RedemptionDate | +DateTime | +Yes | +
Migrate to OpenIddict 1.0/2.0
+What's new?
+The announcement listing the changes introduced in this milestone can be found here.
+Update your packages references
For that, simply update your .csproj file to point to the newest OpenIddict packages:
ASP.NET Core 1.x
<ItemGroup>
@@ -86,9 +254,9 @@
</ItemGroup>
No additional change should be required for basic scenarios.
Migrate to OpenIddict 1.0/2.0 rc3
-What's new?
+What's new?
The announcement listing the changes introduced in this milestone can be found here.
-Update your packages references
+Update your packages references
For that, simply update your .csproj file to point to the newest OpenIddict packages:
ASP.NET Core 1.x
<ItemGroup>
@@ -275,10 +443,10 @@ await _applicationManager.CreateAsync(descriptor);
});
Migrate to OpenIddict 1.0/2.0 rc2
-What's new?
+What's new?
The full list of changes can be found here. 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.
-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 to your database: existing properties have been reworked
(e.g to work around a MySQL limitation) and new ones have been added to support the new features.
This procedure is quite easy and only requires a few minutes.
Tip
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.
@@ -298,7 +466,7 @@ folder in your application root folder and an __EFMigrationsHistory
Version="2.0.0" />
</ItemGroup>
Then, open a new command line and add an initial migration using dotnet ef migrations add InitialMigration (but don't apply it!).
Update your packages references
+Update your packages references
For that, simply update your .csproj file to point to the newest OpenIddict packages:
ASP.NET Core 1.x
<ItemGroup>
@@ -401,7 +569,7 @@ ticket.SetResources("tracking_api", "marketing_api");
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.
To learn more about this feature, read the Application permissions documentation.
-List of changes (for applications using custom stores)
+List of schema changes (for applications using custom stores)
Renamed properties
@@ -451,7 +619,7 @@ controlling and limiting the OAuth2/OpenID Connect features a client application
-Updated properties
+Updated properties
@@ -478,7 +646,7 @@ controlling and limiting the OAuth2/OpenID Connect features a client application
-Added properties
+Added properties
diff --git a/manifest.json b/manifest.json
index 6b2d7db..97dcc4e 100644
--- a/manifest.json
+++ b/manifest.json
@@ -7125,7 +7125,7 @@
"output": {
".html": {
"relative_path": "guide/migration.html",
- "hash": "UjHazjyL1Mr9eW0TEYyQUw=="
+ "hash": "M7OL8gPeEd1bTMoz8QyBfA=="
}
},
"is_incremental": false,