<h1id="migrate-to-openiddict-40">Migrate to OpenIddict 4.0</h1>
<h2id="whats-new">What's new?</h2>
<p>The most important changes introduced in 4.0 can be found <ahref="https://github.com/openiddict/openiddict-core/releases">here</a>.</p>
<divclass="NOTE"><h5>Note</h5><p><strong>Unless you're using MongoDB, migrating to OpenIddict 4.0 doesn't require making changes to your database</strong>.</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</code> 4.x packages. For instance:</p>
</code></pre><divclass="NOTE"><h5>Note</h5><p>Migrating to ASP.NET Core 7.0 is not required, as OpenIddict 4.0 is still natively compatible with ASP.NET Core 2.1 (.NET Framework-only),
ASP.NET Core 3.1 and ASP.NET Core 6.0. Moving to a newer .NET runtime or ASP.NET Core can be done separately for a simpler/decoupled upgrade:</p>
<table>
<thead>
<tr>
<th>Web framework version</th>
<th>.NET runtime version</th>
</tr>
</thead>
<tbody>
<tr>
<td>ASP.NET Core 2.1</td>
<td>.NET Framework 4.6.1</td>
</tr>
<tr>
<td>ASP.NET Core 2.1</td>
<td>.NET Framework 4.7.2</td>
</tr>
<tr>
<td>ASP.NET Core 2.1</td>
<td>.NET Framework 4.8</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
<tr>
<td>ASP.NET Core 3.1</td>
<td>.NET Core 3.1</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
<tr>
<td>ASP.NET Core 6.0</td>
<td>.NET 6.0</td>
</tr>
<tr>
<td>ASP.NET Core 7.0</td>
<td>.NET 7.0</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
<tr>
<td>Microsoft.Owin 4.2</td>
<td>.NET Framework 4.6.1</td>
</tr>
<tr>
<td>Microsoft.Owin 4.2</td>
<td>.NET Framework 4.7.2</td>
</tr>
<tr>
<td>Microsoft.Owin 4.2</td>
<td>.NET Framework 4.8</td>
</tr>
</tbody>
</table>
</div>
<h2id="update-your-endpoint-uris">Update your endpoint URIs</h2>
<p>OpenIddict 4.0 introduces a behavior change that affects how endpoint URIs are computed and resolved. For more information about this change,
read <ahref="https://github.com/openiddict/openiddict-core/issues/1613">Breaking changes in OpenIddict 4.0 impacting how URIs are handled</a>.</p>
<p>In most cases, tweaking your code should be limited to removing the leading slashes in your endpoint paths to account for the new logic:</p>
</code></pre><h2id="remove-calls-to-addclaims-that-specify-a-list-of-destinations">Remove calls to <code>AddClaim(s)</code> that specify a list of destinations:</h2>
<p>As explained in <ahref="https://kevinchalet.com/2022/06/22/openiddict-4-0-preview1-is-out/">OpenIddict 4.0 preview1 is out</a>,
the <code>AddClaim(s)</code> extensions that accepted a <code>destinations</code> parameter have been removed in 4.0.</p>
<p>Instead, developers are encouraged to use the new one-shot <code>SetDestinations()</code> extension for <code>ClaimsIdentity</code>
and <code>ClaimsPrincipal</code> (that must be called after all the claims have been added to the identity/principal):</p>
<pre><codeclass="lang-csharp">var identity = new ClaimsIdentity(
// Otherwise, only store the claim in the access tokens.
_ => new[] { Destinations.AccessToken }
});
</code></pre><h2id="if-applicable-update-your-openiddict-mongodb-authorizations">If applicable, update your OpenIddict MongoDB authorizations</h2>
<p>To match the casing used by the other properties, the name used in the BSON representation of the <code>OpenIddictMongoDbAuthorization.CreationDate</code>
property was fixed to use camel case (i.e <code>creation_name</code> instead of <code>CreationDate</code>). To ensure the existing authorizations are correctly
updated to use the new name, the following script can be used to update all the existing authorizations at once very efficiently:</p>
</code></pre><h2id="if-applicable-replace-references-to-portablebouncycastle-by-bouncycastlecryptography">If applicable, replace references to <code>Portable.BouncyCastle</code> by <code>BouncyCastle.Cryptography</code></h2>
<p>While previous versions of OpenIddict used the unofficial <ahref="https://www.nuget.org/packages/Portable.BouncyCastle"><code>Portable.BouncyCastle</code></a>
package maintained by <ahref="https://github.com/clairernovotny">Claire Novotny</a> (which was the best .NET Standard-compatible option at the time),
OpenIddict 4.0 was updated to use the official package, <ahref="https://www.nuget.org/packages/BouncyCastle.Cryptography">BouncyCastle.Cryptography</a>,
that was released in November 2022 with complete .NET Standard 2.0 support.</p>
<p>If your application uses <code>Portable.BouncyCastle</code>, it is strongly recommended to migrate to <code>BouncyCastle.Cryptography</code> to avoid type conflicts.</p>
<h2id="if-applicable-update-your-custom-stores-to-use-the-updated-signatures">If applicable, update your custom stores to use the updated signatures</h2>
<p>OpenIddict 4.x fixes the nullability annotations of <code>IOpenIddictApplicationStore.GetAsync()</code>, <code>IOpenIddictAuthorizationStore.GetAsync()</code>,
<code>IOpenIddictScopeStore.GetAsync()</code> and <code>IOpenIddictTokenStore.GetAsync()</code> to return <code>ValueTask<TResult?></code> instead of <code>ValueTask<TResult></code>.</p>
<p>Developers who implemented these interfaces <em>and</em> enabled nullable references are invited to update the signature of the <code>GetAsync()</code> methods:</p>
</code></pre><p>While not required, it is recommended to also update implementations of <code>IOpenIddictApplicationStore</code> to use the updated parameter names
for <code>FindByPostLogoutRedirectUriAsync()</code>, <code>FindByRedirectUriAsync()</code>, <code>SetPostLogoutRedirectUrisAsync()</code> and <code>SetRedirectUrisAsync()</code>:</p>
<p>For more information, read <ahref="https://kevinchalet.com/2022/12/23/openiddict-4-0-general-availability/">OpenIddict 4.0 general availability</a>.</p>
