mirror of
https://gitee.com/dcren/openiddict-documentation.git
synced 2025-04-24 18:04:57 +08:00
Update the documentation pages
This commit is contained in:
OpenIddict Bot
parent
78ff179c3b
commit
8a1650c6e4
@ -5,9 +5,9 @@
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||||
<title>What's new in OpenIddict RC2? </title>
|
||||
<title>Migrate to OpenIddict RC3 </title>
|
||||
<meta name="viewport" content="width=device-width">
|
||||
<meta name="title" content="What's new in OpenIddict RC2? ">
|
||||
<meta name="title" content="Migrate to OpenIddict RC3 ">
|
||||
<meta name="generator" content="docfx 2.24.0.0">
|
||||
|
||||
<link rel="shortcut icon" href="../favicon.ico">
|
||||
@ -67,15 +67,209 @@
|
||||
<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>
|
||||
<h1 id="migrate-to-openiddict-rc3">Migrate to OpenIddict RC3</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>
|
||||
<h2 id="whats-new-in-openiddict-rc3">What's new in OpenIddict RC3?</h2>
|
||||
<p>The announcement listing the changes introduced in this milestone can be found <a href="https://kevinchalet.com/2018/06/20/openiddict-rc3-is-out/">here</a>.</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-rc3-final" />
|
||||
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="1.0.0-rc3-final" />
|
||||
</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-rc3-final" />
|
||||
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-rc3-final" />
|
||||
</ItemGroup>
|
||||
</code></pre><div class="TIP"><h5>Tip</h5><p>Note: if you have an explicit reference to <code>AspNet.Security.OAuth.Validation</code> or <code>OpenIddict.Mvc</code>,
|
||||
you can safely remove these dependencies: they are now transitively referenced by the <code>OpenIddict</code> metapackage.</p>
|
||||
</div>
|
||||
<div class="IMPORTANT"><h5>Important</h5><p>Note: 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>
|
||||
</div>
|
||||
<h2 id="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>
|
||||
<pre><code class="lang-csharp">// In OpenIddict RC2, all the options used to be grouped.
|
||||
services.AddOpenIddict(options =>
|
||||
{
|
||||
options.AddEntityFrameworkCoreStores<ApplicationDbContext>();
|
||||
|
||||
options.AddMvcBinders();
|
||||
|
||||
options.EnableAuthorizationEndpoint("/connect/authorize")
|
||||
.EnableLogoutEndpoint("/connect/logout")
|
||||
.EnableTokenEndpoint("/connect/token")
|
||||
.EnableUserinfoEndpoint("/api/userinfo");
|
||||
|
||||
options.AllowAuthorizationCodeFlow()
|
||||
.AllowPasswordFlow()
|
||||
.AllowRefreshTokenFlow();
|
||||
|
||||
options.RegisterScopes(OpenIdConnectConstants.Scopes.Email,
|
||||
OpenIdConnectConstants.Scopes.Profile,
|
||||
OpenIddictConstants.Scopes.Roles);
|
||||
|
||||
options.RequireClientIdentification();
|
||||
|
||||
options.EnableRequestCaching();
|
||||
|
||||
options.EnableScopeValidation();
|
||||
|
||||
options.DisableHttpsRequirement();
|
||||
});
|
||||
</code></pre><pre><code class="lang-csharp">// In OpenIddict RC3, the options are now split into 3 categories:
|
||||
// the core services, the server services and the validation services.
|
||||
services.AddOpenIddict()
|
||||
.AddCore(options =>
|
||||
{
|
||||
// AddEntityFrameworkCoreStores() is now UseEntityFrameworkCore().
|
||||
options.UseEntityFrameworkCore()
|
||||
.UseDbContext<ApplicationDbContext>();
|
||||
})
|
||||
|
||||
.AddServer(options =>
|
||||
{
|
||||
// AddMvcBinders() is now UseMvc().
|
||||
options.UseMvc();
|
||||
|
||||
options.EnableAuthorizationEndpoint("/connect/authorize")
|
||||
.EnableLogoutEndpoint("/connect/logout")
|
||||
.EnableTokenEndpoint("/connect/token")
|
||||
.EnableUserinfoEndpoint("/api/userinfo");
|
||||
|
||||
options.AllowAuthorizationCodeFlow()
|
||||
.AllowPasswordFlow()
|
||||
.AllowRefreshTokenFlow();
|
||||
|
||||
options.RegisterScopes(OpenIdConnectConstants.Scopes.Email,
|
||||
OpenIdConnectConstants.Scopes.Profile,
|
||||
OpenIddictConstants.Scopes.Roles);
|
||||
|
||||
// This API was removed as client identification is now
|
||||
// required by default. You can remove or comment this line.
|
||||
//
|
||||
// options.RequireClientIdentification();
|
||||
|
||||
options.EnableRequestCaching();
|
||||
|
||||
// This API was removed as scope validation is now enforced
|
||||
// by default. You can safely remove or comment this line.
|
||||
//
|
||||
// options.EnableScopeValidation();
|
||||
|
||||
options.DisableHttpsRequirement();
|
||||
});
|
||||
</code></pre><h2 id="move-to-the-openiddict-validation-handler-optional">Move to the OpenIddict validation handler (optional)</h2>
|
||||
<p>While not required, moving to the new validation handler is recommended:</p>
|
||||
<pre><code class="lang-csharp">// Replace...
|
||||
services.AddAuthentication()
|
||||
.AddOAuthValidation();
|
||||
|
||||
// ... by:
|
||||
services.AddOpenIddict()
|
||||
.AddValidation();
|
||||
</code></pre><div class="TIP"><h5>Tip</h5><p>Note: the OpenIddict validation handler lives in the <code>OpenIddict.Validation</code> package, which is referenced by the <code>OpenIddict</code> metapackage.
|
||||
You don't have to explicitly add a new <code>PackageReference</code> in your <code>.csproj</code> file to be able to use it.</p>
|
||||
</div>
|
||||
<h2 id="if-necessary-create-new-application-entries">If necessary, create new application entries</h2>
|
||||
<p>OpenIddict now rejects unauthenticated token/revocation requests by default.</p>
|
||||
<p>If, after migrating to RC3, you see errors similar to this one:</p>
|
||||
<blockquote><p><strong>invalid_request</strong> : The mandatory 'client_id' parameter is missing.</p>
|
||||
</blockquote>
|
||||
<p>Add an application entry for the client application and send the corresponding <code>client_id</code> as part of the token request:</p>
|
||||
<pre><code class="lang-csharp">var descriptor = new OpenIddictApplicationDescriptor
|
||||
{
|
||||
ClientId = "postman",
|
||||
DisplayName = "Postman",
|
||||
Permissions =
|
||||
{
|
||||
OpenIddictConstants.Permissions.Endpoints.Token,
|
||||
OpenIddictConstants.Permissions.GrantTypes.Password,
|
||||
OpenIddictConstants.Permissions.GrantTypes.RefreshToken,
|
||||
OpenIddictConstants.Permissions.Scopes.Email,
|
||||
OpenIddictConstants.Permissions.Scopes.Profile,
|
||||
OpenIddictConstants.Permissions.Scopes.Roles
|
||||
}
|
||||
};
|
||||
|
||||
await _applicationManager.CreateAsync(descriptor);
|
||||
</code></pre><p>If you prefer accepting anonymous clients, use <code>options.AcceptAnonymousClients()</code>:</p>
|
||||
<pre><code class="lang-csharp">services.AddOpenIddict()
|
||||
.AddServer(options =>
|
||||
{
|
||||
options.AcceptAnonymousClients();
|
||||
});
|
||||
</code></pre><h2 id="if-necessary-register-the-scopes-used-by-your-clients">If necessary, register the scopes used by your clients</h2>
|
||||
<p>Starting with RC3, OpenIddict will reject unrecognized scopes by default.</p>
|
||||
<p>If, after migrating to RC3, you see errors similar to this one:</p>
|
||||
<blockquote><p><strong>invalid_scope</strong> : The specified 'scope' parameter is not valid.</p>
|
||||
</blockquote>
|
||||
<p>Simply add the scopes you want to use to the list of registered scopes:</p>
|
||||
<pre><code class="lang-csharp">services.AddOpenIddict()
|
||||
|
||||
// Register the OpenIddict server handler.
|
||||
.AddServer(options =>
|
||||
{
|
||||
options.RegisterScopes(OpenIdConnectConstants.Scopes.Email,
|
||||
OpenIdConnectConstants.Scopes.Profile,
|
||||
OpenIddictConstants.Scopes.Roles);
|
||||
});
|
||||
</code></pre><p>If you prefer disabling scope validation, use <code>options.DisableScopeValidation()</code>:</p>
|
||||
<pre><code class="lang-csharp">services.AddOpenIddict()
|
||||
.AddServer(options =>
|
||||
{
|
||||
options.DisableScopeValidation();
|
||||
});
|
||||
</code></pre><h2 id="if-necessary-adjust-the-permissions-granted-to-your-clients">If necessary, adjust the permissions granted to your clients</h2>
|
||||
<p><strong>Starting with RC3, permissions are no longer optional nor implicit</strong>:
|
||||
if you don't explicitly grant an application the necessary permissions, it will be blocked by OpenIddict.</p>
|
||||
<p>To attach permissions to an application, use <code>OpenIddictApplicationManager</code>:</p>
|
||||
<pre><code class="lang-csharp">var descriptor = new OpenIddictApplicationDescriptor
|
||||
{
|
||||
ClientId = "mvc",
|
||||
ClientSecret = "901564A5-E7FE-42CB-B10D-61EF6A8F3654",
|
||||
DisplayName = "MVC client application",
|
||||
PostLogoutRedirectUris = { new Uri("http://localhost:53507/signout-callback-oidc") },
|
||||
RedirectUris = { new Uri("http://localhost:53507/signin-oidc") },
|
||||
Permissions =
|
||||
{
|
||||
OpenIddictConstants.Permissions.Endpoints.Authorization,
|
||||
OpenIddictConstants.Permissions.Endpoints.Logout,
|
||||
OpenIddictConstants.Permissions.Endpoints.Token,
|
||||
OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode,
|
||||
OpenIddictConstants.Permissions.GrantTypes.RefreshToken,
|
||||
OpenIddictConstants.Permissions.Scopes.Email,
|
||||
OpenIddictConstants.Permissions.Scopes.Profile,
|
||||
OpenIddictConstants.Permissions.Scopes.Roles
|
||||
}
|
||||
};
|
||||
|
||||
await _applicationManager.CreateAsync(descriptor);
|
||||
</code></pre><p>If you don't care about permissions (e.g because you don't have third-party clients), you can instead disable them:</p>
|
||||
<pre><code class="lang-csharp">services.AddOpenIddict()
|
||||
|
||||
// Register the OpenIddict server handler.
|
||||
.AddServer(options =>
|
||||
{
|
||||
options.IgnoreEndpointPermissions()
|
||||
.IgnoreGrantTypePermissions()
|
||||
.IgnoreScopePermissions();
|
||||
});
|
||||
</code></pre><hr>
|
||||
<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>
|
||||
<h2 id="whats-new-in-openiddict-rc2">What's new in OpenIddict RC2?</h2>
|
||||
<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>
|
||||
<p><strong>Migrating to OpenIddict RC2 (<code>1.0.0-rc2-final</code> and <code>2.0.0-rc2-final</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><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"
|
||||
@ -91,15 +285,15 @@
|
||||
<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-*" />
|
||||
<PackageReference Include="OpenIddict" Version="1.0.0-rc2-final" />
|
||||
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="1.0.0-rc2-final" />
|
||||
<PackageReference Include="OpenIddict.Mvc" Version="1.0.0-rc2-final" />
|
||||
</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-*" />
|
||||
<PackageReference Include="OpenIddict" Version="2.0.0-rc2-final" />
|
||||
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-rc2-final" />
|
||||
<PackageReference Include="OpenIddict.Mvc" Version="2.0.0-rc2-final" />
|
||||
</ItemGroup>
|
||||
</code></pre><h2 id="add-a-new-migration">Add a new migration</h2>
|
||||
<ol>
|
||||
@ -190,8 +384,8 @@ ticket.SetResources("tracking_api", "marketing_api");
|
||||
<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>
|
||||
<h2 id="list-of-changes-for-applications-using-custom-stores">List of changes (for applications using custom stores)</h2>
|
||||
<h3 id="renamed-properties">Renamed properties</h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
@ -240,7 +434,7 @@ controlling and limiting the OAuth2/OpenID Connect features a client application
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2 id="updated-properties">Updated properties</h2>
|
||||
<h3 id="updated-properties">Updated properties</h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
@ -267,7 +461,7 @@ controlling and limiting the OAuth2/OpenID Connect features a client application
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2 id="added-properties">Added properties</h2>
|
||||
<h3 id="added-properties">Added properties</h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
|
||||
@ -140,7 +140,7 @@
|
||||
"output": {
|
||||
".html": {
|
||||
"relative_path": "guide/migration.html",
|
||||
"hash": "mAZUkc9pqaTHFLWIYyzbyw=="
|
||||
"hash": "6tP/DNETPLHvVYC7lFgG6A=="
|
||||
}
|
||||
},
|
||||
"is_incremental": false,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user