mirror of
https://gitee.com/dcren/openiddict-documentation.git
synced 2025-04-23 06:05:45 +08:00
337 lines
14 KiB
HTML
337 lines
14 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>What's new in OpenIddict RC2? </title>
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="title" content="What's new in OpenIddict RC2? ">
|
|
<meta name="generator" content="docfx 2.24.0.0">
|
|
|
|
<link rel="shortcut icon" href="../favicon.ico">
|
|
<link rel="stylesheet" href="../styles/docfx.vendor.css">
|
|
<link rel="stylesheet" href="../styles/docfx.css">
|
|
<link rel="stylesheet" href="../styles/main.css">
|
|
<meta property="docfx:navrel" content="../toc.html">
|
|
<meta property="docfx:tocrel" content="toc.html">
|
|
|
|
|
|
|
|
</head>
|
|
<body data-spy="scroll" data-target="#affix">
|
|
<div id="wrapper">
|
|
<header>
|
|
|
|
<nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
|
|
<div class="container">
|
|
<div class="navbar-header">
|
|
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
|
|
<span class="sr-only">Toggle navigation</span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</button>
|
|
|
|
<a class="navbar-brand" href="../index.html">
|
|
<img id="logo" class="svg" src="../logo.svg" alt="">
|
|
</a>
|
|
</div>
|
|
<div class="collapse navbar-collapse" id="navbar">
|
|
<form class="navbar-form navbar-right" role="search" id="search">
|
|
<div class="form-group">
|
|
<input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
|
|
</div>
|
|
</form>
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div class="subnav navbar navbar-default">
|
|
<div class="container hide-when-search" id="breadcrumb">
|
|
<ul class="breadcrumb">
|
|
<li></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</header>
|
|
<div role="main" class="container body-content hide-when-search">
|
|
|
|
<div class="sidenav hide-when-search">
|
|
<a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
|
|
<div class="sidetoggle collapse" id="sidetoggle">
|
|
<div id="sidetoc"></div>
|
|
</div>
|
|
</div>
|
|
<div class="article row grid-right">
|
|
<div class="col-md-10">
|
|
<article class="content wrap" id="_content" data-uid="">
|
|
<h1 id="whats-new-in-openiddict-rc2">What's new in OpenIddict RC2?</h1>
|
|
|
|
<p>The full list of changes can be found <a href="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>
|
|
<h1 id="migrate-to-openiddict-rc2">Migrate to OpenIddict RC2</h1>
|
|
<p><strong>Migrating to OpenIddict RC2 (<code>1.0.0-rc2-*</code> and <code>2.0.0-rc2-*</code>) requires making changes in your database</strong>: existing properties have been reworked (e.g <a href="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>
|
|
<blockquote><p>Note: 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. A list of added/updated/renamed columns is available at the end of this guide.</p>
|
|
</blockquote>
|
|
<h2 id="ensure-migrations-are-correctly-enabled-for-your-project">Ensure migrations are correctly enabled for your project</h2>
|
|
<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>
|
|
<pre><code class="lang-xml"><ItemGroup>
|
|
<PackageReference Include="Microsoft.EntityFrameworkCore.Design"
|
|
Version="2.0.0" PrivateAssets="All" />
|
|
</ItemGroup>
|
|
|
|
<ItemGroup>
|
|
<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet"
|
|
Version="2.0.0" />
|
|
</ItemGroup>
|
|
</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>
|
|
<h2 id="update-your-packages-references">Update your packages references</h2>
|
|
<p>For that, simply update your <code>.csproj</code> file to point to the newest OpenIddict packages:</p>
|
|
<h3 id="aspnet-core-1x">ASP.NET Core 1.x</h3>
|
|
<pre><code class="lang-xml"><ItemGroup>
|
|
<PackageReference Include="OpenIddict" Version="1.0.0-rc2-*" />
|
|
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="1.0.0-rc2-*" />
|
|
<PackageReference Include="OpenIddict.Mvc" Version="1.0.0-rc2-*" />
|
|
</ItemGroup>
|
|
</code></pre><h3 id="aspnet-core-2x">ASP.NET Core 2.x</h3>
|
|
<pre><code class="lang-xml"><ItemGroup>
|
|
<PackageReference Include="OpenIddict" Version="2.0.0-rc2-*" />
|
|
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-rc2-*" />
|
|
<PackageReference Include="OpenIddict.Mvc" Version="2.0.0-rc2-*" />
|
|
</ItemGroup>
|
|
</code></pre><h2 id="add-a-new-migration">Add a new migration</h2>
|
|
<ol>
|
|
<li>First, open a new command line and run <code>dotnet ef migrations add MigrateToOpenIddictRc2</code>.</li>
|
|
<li><strong>If you created an initial migration at step 1, remove it from the <code>Migrations</code> folder</strong>.</li>
|
|
<li>Apply the <code>MigrateToOpenIddictRc2</code> migration using <code>dotnet ef database update MigrateToOpenIddictRc2</code>.</li>
|
|
</ol>
|
|
<h2 id="run-the-migration-script-to-convert-columns-to-the-new-format">Run the migration script to convert columns to the new format</h2>
|
|
<p>For that, add the following snippet to your <code>Startup</code> class:</p>
|
|
<pre><code class="lang-csharp">private async Task UpdateOpenIddictTablesAsync(IServiceProvider services)
|
|
{
|
|
using (var scope = services.GetRequiredService<IServiceScopeFactory>().CreateScope())
|
|
{
|
|
// Change ApplicationDbContext to match your context name if you've changed it.
|
|
var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
|
|
await context.Database.EnsureCreatedAsync();
|
|
|
|
// If you use a different entity type or a custom key,
|
|
// change this line (e.g OpenIddictApplication<long>).
|
|
foreach (var application in context.Set<OpenIddictApplication>())
|
|
{
|
|
// Convert the space-separated PostLogoutRedirectUris property to JSON.
|
|
if (!string.IsNullOrEmpty(application.PostLogoutRedirectUris) &&
|
|
application.PostLogoutRedirectUris[0] != '[')
|
|
{
|
|
var addresses = application.PostLogoutRedirectUris.Split(
|
|
new[] { " " }, StringSplitOptions.RemoveEmptyEntries);
|
|
|
|
application.PostLogoutRedirectUris =
|
|
new JArray(addresses).ToString(Formatting.None);
|
|
}
|
|
|
|
// Convert the space-separated RedirectUris property to JSON.
|
|
if (!string.IsNullOrEmpty(application.RedirectUris) &&
|
|
application.RedirectUris[0] != '[')
|
|
{
|
|
var addresses = application.RedirectUris.Split(
|
|
new[] { " " }, StringSplitOptions.RemoveEmptyEntries);
|
|
|
|
application.RedirectUris = new JArray(addresses).ToString(Formatting.None);
|
|
}
|
|
}
|
|
|
|
// If you use a different entity type or a custom key,
|
|
// change this line (e.g OpenIddictAuthorization<long>).
|
|
foreach (var authorization in context.Set<OpenIddictAuthorization>())
|
|
{
|
|
// Convert the space-separated Scopes property to JSON.
|
|
if (!string.IsNullOrEmpty(authorization.Scopes) && authorization.Scopes[0] != '[')
|
|
{
|
|
var scopes = authorization.Scopes.Split(
|
|
new[] { " " }, StringSplitOptions.RemoveEmptyEntries);
|
|
|
|
authorization.Scopes = new JArray(scopes).ToString(Formatting.None);
|
|
}
|
|
}
|
|
|
|
await context.SaveChangesAsync();
|
|
}
|
|
}
|
|
</code></pre><p>Then, at the end of the <code>public void Configure(IApplicationBuilder app)</code> method, add the following line:</p>
|
|
<pre><code class="lang-csharp">public void Configure(IApplicationBuilder app)
|
|
{
|
|
app.UseDeveloperExceptionPage();
|
|
|
|
app.UseStaticFiles();
|
|
|
|
app.UseStatusCodePagesWithReExecute("/error");
|
|
|
|
app.UseAuthentication();
|
|
|
|
app.UseMvcWithDefaultRoute();
|
|
|
|
// Run the migration script synchronously.
|
|
UpdateOpenIddictTablesAsync(app.ApplicationServices).GetAwaiter().GetResult();
|
|
}
|
|
</code></pre><p>Run your application. Once it's correctly started, stop it and remove the migration script.</p>
|
|
<h2 id="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><code class="lang-csharp">var ticket = new AuthenticationTicket(
|
|
new ClaimsPrincipal(identity),
|
|
new AuthenticationProperties(),
|
|
OpenIdConnectServerDefaults.AuthenticationScheme);
|
|
|
|
ticket.SetResources("tracking_api", "marketing_api");
|
|
</code></pre><h2 id="optionally-update-your-code-to-grant-applications-the-minimum-required-permissions">Optionally, update your code to grant applications the minimum required permissions</h2>
|
|
<p>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.</p>
|
|
<p>To learn more about this feature, read the <a href="../features/application-permissions.html">Application permissions documentation</a>.</p>
|
|
<h1 id="list-of-changes-for-applications-using-custom-stores">List of changes (for applications using custom stores)</h1>
|
|
<h2 id="renamed-properties">Renamed properties</h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Table</th>
|
|
<th>Old column name</th>
|
|
<th>New column name</th>
|
|
<th>Observations</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>OpenIddictApplications</td>
|
|
<td>Timestamp</td>
|
|
<td>ConcurrencyToken</td>
|
|
<td>The column type was changed to nvarchar to work around a MySQL limitation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictAuthorizations</td>
|
|
<td>Timestamp</td>
|
|
<td>ConcurrencyToken</td>
|
|
<td>The column type was changed to nvarchar to work around a MySQL limitation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictScopes</td>
|
|
<td>Timestamp</td>
|
|
<td>ConcurrencyToken</td>
|
|
<td>The column type was changed to nvarchar to work around a MySQL limitation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictTokens</td>
|
|
<td>Timestamp</td>
|
|
<td>ConcurrencyToken</td>
|
|
<td>The column type was changed to nvarchar to work around a MySQL limitation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictTokens</td>
|
|
<td>Ciphertext</td>
|
|
<td>Payload</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictTokens</td>
|
|
<td>Hash</td>
|
|
<td>ReferenceId</td>
|
|
<td></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h2 id="added-properties">Added properties</h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Table</th>
|
|
<th>Column name</th>
|
|
<th>Type</th>
|
|
<th>Nullable</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>OpenIddictApplications</td>
|
|
<td>Properties</td>
|
|
<td>nvarchar(max)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictApplications</td>
|
|
<td>Permissions</td>
|
|
<td>nvarchar(max)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictAuthorizations</td>
|
|
<td>Properties</td>
|
|
<td>nvarchar(max)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictScopes</td>
|
|
<td>DisplayName</td>
|
|
<td>nvarchar(max)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictScopes</td>
|
|
<td>Properties</td>
|
|
<td>nvarchar(max)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictScopes</td>
|
|
<td>Resources</td>
|
|
<td>nvarchar(max)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>OpenIddictTokens</td>
|
|
<td>Properties</td>
|
|
<td>nvarchar(max)</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</article>
|
|
</div>
|
|
|
|
<div class="hidden-sm col-md-2" role="complementary">
|
|
<div class="sideaffix">
|
|
<div class="contribution">
|
|
<ul class="nav">
|
|
<li>
|
|
<a href="https://github.com/openiddict/openiddict-documentation/blob/dev/guide/migration.md/#L1" class="contribution-link">Improve this Doc</a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
|
|
<!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<footer>
|
|
<div class="grad-bottom"></div>
|
|
<div class="footer">
|
|
<div class="container">
|
|
<span class="pull-right">
|
|
<a href="#top">Back to top</a>
|
|
</span>
|
|
|
|
<span>Copyright © 2015-2017 Microsoft<br>Generated by <strong>DocFX</strong></span>
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
</div>
|
|
|
|
<script type="text/javascript" src="../styles/docfx.vendor.js"></script>
|
|
<script type="text/javascript" src="../styles/docfx.js"></script>
|
|
<script type="text/javascript" src="../styles/main.js"></script>
|
|
</body>
|
|
</html>
|