mirror of
https://gitee.com/dcren/openiddict-documentation.git
synced 2025-04-05 17:38:03 +08:00
306 lines
16 KiB
HTML
306 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<!--[if IE]><![endif]-->
|
|
<html>
|
|
|
|
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
|
<title>Migrate to OpenIddict 4.0 </title>
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="title" content="Migrate to OpenIddict 4.0 ">
|
|
<meta name="generator" content="docfx 2.56.7.0">
|
|
|
|
<link rel="shortcut icon" href="../../images/favicon.ico">
|
|
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" rel="stylesheet">
|
|
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/night-owl.min.css">
|
|
<link rel="stylesheet" href="../../styles/colors.css">
|
|
<link rel="stylesheet" href="../../styles/discord.css">
|
|
<link rel="stylesheet" href="../../styles/main.css">
|
|
<meta property="docfx:navrel" content="../../toc.html">
|
|
<meta property="docfx:tocrel" content="../toc.html">
|
|
|
|
|
|
|
|
</head>
|
|
|
|
<body>
|
|
<div class="top-navbar">
|
|
|
|
<a href="javascript:void(0);" class="burger-icon" onclick="toggleMenu()">
|
|
<svg name="Hamburger" style="vertical-align: middle;" width="24" height="24" viewbox="0 0 24 24"><path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="M20 6H4V9H20V6ZM4 10.999H20V13.999H4V10.999ZM4 15.999H20V18.999H4V15.999Z"></path></svg>
|
|
</a>
|
|
|
|
|
|
<a class="brand" href="../../index.html">
|
|
<img src="../../images/logo.png" alt="OpenIddict" class="logomark">
|
|
<span class="brand-title">OpenIddict</span>
|
|
</a>
|
|
</div>
|
|
|
|
<div class="body-content">
|
|
|
|
<div id="blackout" class="blackout" onclick="toggleMenu()"></div>
|
|
|
|
<nav id="sidebar" role="navigation">
|
|
|
|
<div class="sidebar">
|
|
|
|
|
|
|
|
|
|
<div>
|
|
|
|
<a class="brand" href="../../index.html">
|
|
<img src="../../images/logo.png" alt="OpenIddict" class="logomark">
|
|
<span class="brand-title">OpenIddict</span>
|
|
</a>
|
|
<div id="navbar">
|
|
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
<div class="sidebar-item-separator"></div>
|
|
|
|
|
|
<div id="sidetoggle">
|
|
<div id="sidetoc"></div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div class="footer">
|
|
|
|
<span>Generated by <strong>DocFX</strong></span>
|
|
</div>
|
|
</nav>
|
|
|
|
<main class="main-panel">
|
|
|
|
<div role="main" class="hide-when-search">
|
|
|
|
|
|
<div class="subnav navbar navbar-default">
|
|
<div class="container hide-when-search" id="breadcrumb">
|
|
<ul class="breadcrumb">
|
|
<li></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<article class="content wrap" id="_content" data-uid="">
|
|
<h1 id="migrate-to-openiddict-40">Migrate to OpenIddict 4.0</h1>
|
|
|
|
<h2 id="whats-new">What's new?</h2>
|
|
<p>The most important changes introduced in 4.0 can be found <a href="https://github.com/openiddict/openiddict-core/releases">here</a>.</p>
|
|
<div class="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>
|
|
<h2 id="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>
|
|
<pre><code class="lang-xml"><ItemGroup>
|
|
<!-- OpenIddict 3.x: -->
|
|
<PackageReference Include="OpenIddict.AspNetCore" Version="3.1.1" />
|
|
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="3.1.1" />
|
|
|
|
<!-- OpenIddict 4.x: -->
|
|
<PackageReference Include="OpenIddict.AspNetCore" Version="4.0.0" />
|
|
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="4.0.0" />
|
|
</ItemGroup>
|
|
</code></pre><div class="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>
|
|
<h2 id="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 <a href="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>
|
|
<pre><code class="lang-csharp">services.AddOpenIddict()
|
|
.AddServer(options =>
|
|
{
|
|
// OpenIddict 3.x:
|
|
options.SetAuthorizationEndpointUris("/connect/authorize")
|
|
.SetDeviceEndpointUris("/connect/device")
|
|
.SetIntrospectionEndpointUris("/connect/introspect")
|
|
.SetLogoutEndpointUris("/connect/logout")
|
|
.SetTokenEndpointUris("/connect/token")
|
|
.SetUserinfoEndpointUris("/connect/userinfo")
|
|
.SetVerificationEndpointUris("/connect/verify");
|
|
|
|
// OpenIddict 4.x:
|
|
options.SetAuthorizationEndpointUris("connect/authorize")
|
|
.SetDeviceEndpointUris("connect/device")
|
|
.SetIntrospectionEndpointUris("connect/introspect")
|
|
.SetLogoutEndpointUris("connect/logout")
|
|
.SetTokenEndpointUris("connect/token")
|
|
.SetUserinfoEndpointUris("connect/userinfo")
|
|
.SetVerificationEndpointUris("connect/verify");
|
|
});
|
|
</code></pre><h2 id="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 <a href="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><code class="lang-csharp">var identity = new ClaimsIdentity(
|
|
authenticationType: TokenValidationParameters.DefaultAuthenticationType,
|
|
nameType: Claims.Name,
|
|
roleType: Claims.Role);
|
|
|
|
identity.SetClaim(Claims.Subject, await _userManager.GetUserIdAsync(user))
|
|
.SetClaim(Claims.Email, await _userManager.GetEmailAsync(user))
|
|
.SetClaim(Claims.Name, await _userManager.GetUserNameAsync(user))
|
|
.SetClaims(Claims.Role, (await _userManager.GetRolesAsync(user)).ToImmutableArray());
|
|
|
|
identity.SetScopes(result.Principal.GetScopes());
|
|
identity.SetResources(await _scopeManager.ListResourcesAsync(identity.GetScopes()).ToListAsync());
|
|
|
|
identity.SetDestinations(static claim => claim.Type switch
|
|
{
|
|
// Allow the "name" claim to be stored in both the access and identity tokens
|
|
// when the "profile" scope was granted (by calling principal.SetScopes(...)).
|
|
Claims.Name when claim.Subject.HasScope(Scopes.Profile)
|
|
=> new[] { Destinations.AccessToken, Destinations.IdentityToken },
|
|
|
|
// Otherwise, only store the claim in the access tokens.
|
|
_ => new[] { Destinations.AccessToken }
|
|
});
|
|
</code></pre><h2 id="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>
|
|
<pre><code class="lang-csharp">using Microsoft.Extensions.DependencyInjection;
|
|
using Microsoft.Extensions.Options;
|
|
using MongoDB.Bson;
|
|
using MongoDB.Driver;
|
|
using OpenIddict.MongoDb;
|
|
|
|
var services = new ServiceCollection();
|
|
services.AddOpenIddict()
|
|
.AddCore()
|
|
.UseMongoDb()
|
|
.UseDatabase(new MongoClient("mongodb://localhost:27017").GetDatabase("openiddict"));
|
|
|
|
await using var provider = services.BuildServiceProvider();
|
|
var context = provider.GetRequiredService<IOpenIddictMongoDbContext>();
|
|
var options = provider.GetRequiredService<IOptionsMonitor<OpenIddictMongoDbOptions>>().CurrentValue;
|
|
var database = await context.GetDatabaseAsync(CancellationToken.None);
|
|
|
|
var authorizations = database.GetCollection<BsonDocument>(options.AuthorizationsCollectionName);
|
|
await authorizations.UpdateManyAsync(
|
|
filter: Builders<BsonDocument>.Filter.Empty,
|
|
update: Builders<BsonDocument>.Update.Rename("CreationDate", "creation_date"));
|
|
</code></pre><h2 id="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 <a href="https://www.nuget.org/packages/Portable.BouncyCastle"><code>Portable.BouncyCastle</code></a>
|
|
package maintained by <a href="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, <a href="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>
|
|
<h2 id="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>
|
|
<pre><code class="lang-csharp">// OpenIddict 3.x:
|
|
ValueTask<TResult> GetAsync<TState, TResult>(
|
|
Func<IQueryable<TApplication>, TState, IQueryable<TResult>> query,
|
|
TState state, CancellationToken cancellationToken);
|
|
|
|
// OpenIddict 4.x:
|
|
ValueTask<TResult?> GetAsync<TState, TResult>(
|
|
Func<IQueryable<TApplication>, TState, IQueryable<TResult>> query,
|
|
TState state, CancellationToken cancellationToken);
|
|
</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>
|
|
<pre><code class="lang-csharp">// OpenIddict 3.x:
|
|
IAsyncEnumerable<TApplication> FindByPostLogoutRedirectUriAsync(string address, CancellationToken cancellationToken);
|
|
IAsyncEnumerable<TApplication> FindByRedirectUriAsync(string address, CancellationToken cancellationToken);
|
|
ValueTask SetPostLogoutRedirectUrisAsync(TApplication application, ImmutableArray<string> addresses, CancellationToken cancellationToken);
|
|
ValueTask SetRedirectUrisAsync(TApplication application, ImmutableArray<string> addresses, CancellationToken cancellationToken);
|
|
|
|
// OpenIddict 4.x:
|
|
IAsyncEnumerable<TApplication> FindByPostLogoutRedirectUriAsync(string uri, CancellationToken cancellationToken);
|
|
IAsyncEnumerable<TApplication> FindByRedirectUriAsync(string uri, CancellationToken cancellationToken);
|
|
ValueTask SetPostLogoutRedirectUrisAsync(TApplication application, ImmutableArray<string> uris, CancellationToken cancellationToken);
|
|
ValueTask SetRedirectUrisAsync(TApplication application, ImmutableArray<string> uris, CancellationToken cancellationToken);
|
|
</code></pre><h2 id="consider-migrating-to-the-new-openiddict-client-optional">Consider migrating to the new OpenIddict client (optional)</h2>
|
|
<p>OpenIddict 4.0 introduces a new client stack that is natively compatible with all supported versions of ASP.NET Core (2.1
|
|
on .NET Framework, 3.1, 6.0 and 7.0) and <code>Microsoft.Owin</code> 4.2 (which means it can also be used on ASP.NET 4.6.1 and higher).</p>
|
|
<p>For more information, read <a href="https://kevinchalet.com/2022/12/23/openiddict-4-0-general-availability/">OpenIddict 4.0 general availability</a>.</p>
|
|
</article>
|
|
|
|
</div>
|
|
</main>
|
|
</div>
|
|
|
|
|
|
<script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous"></script>
|
|
<script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
|
|
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>
|
|
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js"></script>
|
|
<script type="text/javascript" src="../../styles/jquery.twbsPagination.js"></script>
|
|
<script type="text/javascript" src="../../styles/url.min.js"></script>
|
|
<script src="https://cdn.jsdelivr.net/npm/anchor-js/anchor.min.js"></script>
|
|
<script type="text/javascript" src="../../styles/docfx.js"></script>
|
|
<script type="text/javascript" src="../../styles/main.js"></script>
|
|
|
|
</body>
|
|
|
|
</html>
|