<h1id="migrate-to-openiddict-30">Migrate to OpenIddict 3.0</h1>
<h2id="whats-new">What's new?</h2>
<p>The announcement listing the changes introduced in this milestone can be found <ahref="https://kevinchalet.com/2020/12/23/openiddict-3-0-general-availability/">here</a>.</p>
<divclass="IMPORTANT"><h5>Important</h5><p><strong>Migrating to OpenIddict 3.0 requires making changes to your database</strong>: existing properties have been reworked and new ones have been added to support the new features.</p>
</code></pre><h2id="ensure-your-application-doesnt-reference-legacyunsupported-packages">Ensure your application doesn't reference legacy/unsupported packages</h2>
<p>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:</p>
<table>
<thead>
<tr>
<th>Package name</th>
</tr>
</thead>
<tbody>
<tr>
<td>AspNet.Security.OpenIdConnect.Extensions</td>
</tr>
<tr>
<td>AspNet.Security.OpenIdConnect.Primitives</td>
</tr>
<tr>
<td>AspNet.Security.OpenIdConnect.Server</td>
</tr>
<tr>
<td></td>
</tr>
<tr>
<td>Owin.Security.OpenIdConnect.Extensions</td>
</tr>
<tr>
<td>Owin.Security.OpenIdConnect.Server</td>
</tr>
<tr>
<td></td>
</tr>
<tr>
<td>AspNet.Security.OAuth.Introspection</td>
</tr>
<tr>
<td>AspNet.Security.OAuth.Validation</td>
</tr>
<tr>
<td></td>
</tr>
<tr>
<td>Owin.Security.OAuth.Introspection</td>
</tr>
<tr>
<td>Owin.Security.OAuth.Validation</td>
</tr>
<tr>
<td></td>
</tr>
<tr>
<td>OpenIddict.Models</td>
</tr>
<tr>
<td>OpenIddict.Mvc</td>
</tr>
</tbody>
</table>
<h2id="update-the-references-to-the-entity-framework-coreentity-framework-6mongodb-models">Update the references to the Entity Framework Core/Entity Framework 6/MongoDB models</h2>
<p>If your application references the <code>OpenIddictApplication</code>, <code>OpenIddictAuthorization</code>, <code>OpenIddictScope</code> or <code>OpenIddictToken</code> models, update these reference to use
their new names: <code>OpenIddict[provider name]Application</code>, <code>OpenIddict[provider name]Authorization</code>, <code>OpenIddict[provider name]Scope</code> and <code>OpenIddict[provider name]Token</code>
(e.g when using MongoDB: <code>OpenIddictMongoDbApplication</code>, <code>OpenIddictMongoDbAuthorization</code>, <code>OpenIddictMongoDbScope</code> and <code>OpenIddictMongoDbToken</code>).</p>
<h2id="enable-aspnet-core-integration-in-the-server-and-validation-options">Enable ASP.NET Core integration in the server and validation options</h2>
<p>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:</p>
</code></pre><h2id="enable-the-authorization-logout-and-token-endpoints-pass-through-mode">Enable the authorization, logout and token endpoints pass-through mode</h2>
<p>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:</p>
</code></pre><h2id="enable-aspnet-core-data-protection-support-to-ensure-existing-tokens-can-still-be-validated">Enable ASP.NET Core Data Protection support to ensure existing tokens can still be validated</h2>
<p>For that, call <code>options.UseDataProtection()</code> in both the server and validation options:</p>
</code></pre><h2id="replace-jsonnet-by-systemtextjson">Replace JSON.NET by <code>System.Text.Json</code></h2>
<p>If you use JSON.NET to serialize or deserialize <code>OpenIdConnectMessage</code>, <code>OpenIdConnectRequest</code> or <code>OpenIdConnectResponse</code> instances,
consider moving to <code>System.Text.Json</code> when migrating to OpenIddict 3.0, as 3.0 no longer includes a built-in JSON.NET <code>JsonConverter</code> for these types.</p>
<p>In most cases, this should be as simple as replacing <code>JsonConvert.SerializeObject()</code>/<code>JsonConvert.DeserializeObject()</code>
by their <code>System.Text.Json</code> equivalent: <code>JsonSerializer.Serialize()</code>/<code>JsonSerializer.Deserialize()</code>.</p>
<h2id="add-an-apply-migrations-if-necessary">Add an apply migrations, if necessary</h2>
<p>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.</p>
<h2id="list-of-schema-changes-for-applications-using-custom-stores">List of schema changes (for applications using custom stores)</h2>
<p>The announcement listing the changes introduced in this milestone can be found <ahref="https://kevinchalet.com/2018/11/01/openiddict-1-0-and-2-0-general-availability/">here</a>.</p>
<p>The announcement listing the changes introduced in this milestone can be found <ahref="https://kevinchalet.com/2018/06/20/openiddict-rc3-is-out/">here</a>.</p>
</code></pre><divclass="TIP"><h5>Tip</h5><p>If you have an explicit reference to <code>AspNet.Security.OAuth.Validation</code> or <code>OpenIddict.Mvc</code>,
<divclass="IMPORTANT"><h5>Important</h5><p>If your application references <code>OpenIddict.Models</code> or <code>OpenIddict.Stores</code>, you MUST remove them as these packages are no longer used in rc3.</p>
<h2id="use-the-new-openiddict-services-registration-apis">Use the new OpenIddict services registration APIs</h2>
<p>To offer a better user experience, the registrations APIs exposed by OpenIddict have been reworked. Updating your code should be quite straightforward:</p>
</code></pre><divclass="TIP"><h5>Tip</h5><p>The OpenIddict validation handler lives in the <code>OpenIddict.Validation</code> package, which is referenced by the <code>OpenIddict</code> metapackage.
<p>The full list of changes can be found <ahref="https://github.com/openiddict/openiddict-core/milestone/8?closed=1">here</a>. It includes <strong>bug fixes</strong> (including a bug fix in the refresh token handling)
and new features like <strong>application permissions</strong>, that allow limiting the OpenID Connect features (endpoints and flows) an application is able to use.</p>
<p><strong>Migrating to OpenIddict rc2 (<code>1.0.0-rc2-final</code> and <code>2.0.0-rc2-final</code>) requires making changes to your database</strong>: existing properties have been reworked
(e.g <ahref="https://github.com/openiddict/openiddict-core/issues/497">to work around a MySQL limitation</a>) and new ones have been added to support the new features.
This procedure is quite easy and only requires a few minutes.</p>
<divclass="TIP"><h5>Tip</h5><p>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.
<p><strong>Before migrating to OpenIddict rc2, make sure migrations are already enabled for your application</strong>. If you have a <code>Migrations</code>
folder in your application root folder and an <code>__EFMigrationsHistory</code> table in your database, you're good to go.</p>
<p>If you don't have these Entity Framework Core artifacts, migrations are likely not enabled. To fix that, add the following entries in your <code>.csproj</code>:</p>
</code></pre><p>Then, open a new command line and add an initial migration using <code>dotnet ef migrations add InitialMigration</code> (<strong>but don't apply it!</strong>).</p>
</code></pre><p>Run your application. Once it's correctly started, stop it and remove the migration script.</p>
<h2id="if-your-authorization-server-uses-introspection-make-sure-resources-are-set-in-the-authentication-ticket">If your authorization server uses introspection, make sure resources are set in the authentication ticket</h2>
<p><strong>Setting an explicit list of resources is now required to allow client applications to introspect a token.</strong>
For that, call <code>ticket.SetResources()</code> with the list of the client identifiers allowed to validate the token. E.g:</p>
<pre><codeclass="lang-csharp">var ticket = new AuthenticationTicket(
</code></pre><h2id="optionally-update-your-code-to-grant-applications-the-minimum-required-permissions">Optionally, update your code to grant applications the minimum required permissions</h2>
