<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>
</div>
<h2id="update-your-packages-references">Update your packages references</h2>
<p>For that, update your <code>.csproj</code> file to reference the <code>OpenIddict.AspNetCore</code> 3.x metapackage:</p>
<divclass="IMPORTANT"><h5>Important</h5><p>If your application references the <code>OpenIdConnectConstants</code> class, update it to use <code>OpenIddictConstants</code> instead.</p>
<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:</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="use-the-new-request-caching-apis-if-applicable">Use the new request caching APIs, if applicable</h2>
<p>In 3.0, the <code>OpenIddictServerBuilder.EnableRequestCaching()</code> API - that enabled request caching for both authorization and logout request -
was replaced by 2 separate methods. If your application depends on request caching, don't forget to enable it when migrating to 3.0:</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 their
<h2id="replace-calls-to-the-authenticationticket-extensions-by-their-new-claimsprincipal-equivalent">Replace calls to the <code>AuthenticationTicket</code> extensions by their new <code>ClaimsPrincipal</code> equivalent:</h2>
<p>OpenIddict 3.0 no longer uses the <code>AuthenticationTicket</code> type provided by ASP.NET Core. Instead, everything is now stored in the <code>ClaimsPrincipal</code> instance.
If you have calls like <code>ticket.SetScopes()</code> or <code>ticket.SetResources()</code>, use their new equivalents (e.g <code>principal.SetScopes()</code> or <code>principal.SetResources()</code>).</p>
<h2id="use-the-new-authentication-schemes">Use the new authentication schemes</h2>
<p>In 3.0, the constants used as the ASP.NET Core authentication schemes have changed:</p>
<divclass="NOTE"><h5>Note</h5><p>In 3.0, the OpenIddict server ASP.NET Core handler supports authenticating userinfo requests. As such, if you use the pass-through mode
to handle userinfo requests in your own userinfo MVC action, consider using <code>OpenIddictServerAspNetCoreDefaults.AuthenticationScheme</code>
instead of <code>OpenIddictValidationAspNetCoreDefaults.AuthenticationScheme</code> for your userinfo endpoint to avoid validating access tokens twice.</p>
</code></pre><p>Alternatively, you can use the check the presence of the private OpenIddict <code>oi_scp</code> claims that use the same format as in 2.x (i.e one claim per scope value):</p>
</code></pre><divclass="CAUTION"><h5>Caution</h5><p>These 2 options only work with the OpenIddict validation handler as the <code>oi_scp</code> claims are not populated by the JWT bearer handler developped by Microsoft.
If you can't migrate to the OpenIddict validation handler, consider splitting the standard <code>scope</code> claim manually to determine whether it contains a specific value.</p>
</div>
<h2id="add-and-apply-migrations-if-necessary">Add and apply migrations, if necessary</h2>
<td>The column is now nullable to support the device authorization flow.</td>
</tr>
<tr>
<td>OpenIddictTokens</td>
<td>CreationDate</td>
<td>For broader database support, this column is a now a <code>DateTime</code> instance.</td>
</tr>
<tr>
<td>OpenIddictTokens</td>
<td>ExpirationDate</td>
<td>For broader database support, this column is a now a <code>DateTime</code> instance.</td>
</tr>
<tr>
<td>OpenIddictTokens</td>
<td>Subject</td>
<td>The column is now nullable to support the device authorization flow.</td>
</tr>
</tbody>
</table>
<h3id="added-properties">Added properties</h3>
<table>
<thead>
<tr>
<th>Table</th>
<th>Column name</th>
<th>Type</th>
<th>Nullable</th>
</tr>
</thead>
<tbody>
<tr>
<td>OpenIddictAuthorizations</td>
<td>CreationDate</td>
<td>DateTime</td>
<td>Yes</td>
</tr>
<tr>
<td>OpenIddictTokens</td>
<td>RedemptionDate</td>
<td>DateTime</td>
<td>Yes</td>
</tr>
</tbody>
</table>
<h2id="if-necessary-enable-hybrid-flow-support-in-the-server-options">If necessary, enable hybrid flow support in the server options</h2>
<p>In 2.0, the hybrid flow was automatically enabled if both the authorization code and implicit flows were enabled. In 3.0, this is no longer true
and the hybrid flow MUST be explicitly opted in. If you use the hybrid flow, make sure your application calls the <code>options.AllowHybridFlow()</code> method:</p>
</code></pre><h2id="update-your-applications-to-grant-them-the-appropriate-response-type-permissions">Update your applications to grant them the appropriate response type permissions</h2>
<p>New response type permissions - enforced by default - <ahref="/configuration/application-permissions.html#response-type-permissions">have been introduced in 3.0</a>.</p>
<divclass="NOTE"><h5>Note</h5><p>If you have many applications to migrate, you can use <ahref="https://github.com/openiddict/openiddict-core/issues/1138#issuecomment-713681158">this script</a>
