UX improvements in OpenIddict RC3

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.

[hoangdovan]

So tired with openiddict always change like this, my project broken because of this change. Why openiddict still rc after so long time and cannot be stable with official release version?

[kinosang]

@hoangdovan as @PinpointTownes said, choose the nightly builds means you accept the risk.

Most of projects have broken changes in nightly builds. It’s unusual to upgrade packages (even rc, rtm or stable version) without having a look at the release note for production environment.