UX improvements in OpenIddict RC3 #593
Description
In this release, we focused on reworking the OpenIddict registration APIs to offer a better user experience.
As part of this change, we split the OpenIddict services into three areas - Core, Server and Validation - and the IServiceCollection APIs have been updated to reflect that:
Each specialized builder only exposes the options that are relevant to its specific area:
Of course, the calls to AddCore(), AddServer() and AddValidation() can be chained:
services.AddOpenIddict()
// Register the OpenIddict core services.
.AddCore(options =>
{
// Register the Entity Framework stores and models.
options.UseEntityFrameworkCore()
.UseDbContext<ApplicationDbContext>();
})
// Register the OpenIddict server handler.
.AddServer(options =>
{
// Register the ASP.NET Core MVC binder used by OpenIddict.
// Note: if you don't call this method, you won't be able to
// bind OpenIdConnectRequest or OpenIdConnectResponse parameters.
options.UseMvc();
// Enable the authorization, logout, token and userinfo endpoints.
options.EnableAuthorizationEndpoint("/connect/authorize")
.EnableLogoutEndpoint("/connect/logout")
.EnableTokenEndpoint("/connect/token")
.EnableUserinfoEndpoint("/api/userinfo");
// Note: the Mvc.Client sample only uses the code flow and the password flow, but you
// can enable the other flows if you need to support implicit or client credentials.
options.AllowAuthorizationCodeFlow()
.AllowPasswordFlow()
.AllowRefreshTokenFlow();
// During development, you can disable the HTTPS requirement.
options.DisableHttpsRequirement();
})
// Register the OpenIddict validation handler.
// Note: the OpenIddict validation handler is only compatible with the
// default token format or with reference tokens and cannot be used with
// JWT tokens. For JWT tokens, use the Microsoft JWT bearer handler.
.AddValidation();Introducing these specialized builders was also a great opportunity to revisit how the OpenIddict entities are registered. In the RC2 bits, this is controlled by the services.AddOpenIddict<...>() method, that determines which entities are used depending on the overload.
In RC3, the generic services.AddOpenIddict<...>() methods have been removed and replaced by a more explicit pattern:
In this release, we also made debugging easier by adding custom exception messages instead of relying on the rather cryptic DI-related messages thrown by ASP.NET Core.
If you forget to register stores, you'll now get a much clearer exception:
System.InvalidOperationException : No application store has been registered in the dependency injection container.
To register the Entity Framework Core stores, reference the 'OpenIddict.EntityFrameworkCore' package and call 'services.AddOpenIddict().AddCore().UseEntityFrameworkCore()'.
To register a custom store, create an implementation of 'IOpenIddictApplicationStore' and use 'services.AddOpenIddict().AddCore().AddApplicationStore()' to add it to the DI container.
If you use an entity that is not compatible with the underlying store, you'll also get a better exception:
System.InvalidOperationException : The specified application type is not compatible with the Entity Framework Core stores.
When enabling the Entity Framework Core stores, make sure you use the built-in 'OpenIddictApplication' entity (from the 'OpenIddict.EntityFrameworkCore.Models' package) or a custom entity that inherits from the generic 'OpenIddictApplication' entity.
Similarly, if you forget to register the core services when enabling the server or validation handlers, you'll get an exception:
System.InvalidOperationException : The core services must be registered when enabling the server handler.
To register the OpenIddict core services, use 'services.AddOpenIddict().AddCore()'.
System.InvalidOperationException : The core services must be registered when enabling reference tokens support.
To register the OpenIddict core services, use 'services.AddOpenIddict().AddCore()'.
Hope you'll appreciate these changes.