Openiddict-core: UX improvements in OpenIddict RC3

[kevinchalet]

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?

[kevinchalet]

Your comment is so aggressive I’m not even sure I want to answer it.

[hoangdovan]

So sorry with this comment, I appreciate your hard work! I'm considering using openiddict in production, but there is some risk... Wish you continue your great effort! Thanks!

[kevinchalet]

I'm considering using openiddict in production, but there is some risk...

Well, it’s a risk you accepted, specially since you decided to use our nightly builds instead of the latest stable release (RC2 at the time of writing).

To answer your question: OpenIddict is not RTM yet because I want to make sure we have the best API design before we ship it as a non-RC package. The improvements mentioned in this thread reflect that as they are based on community feedback and remarks from corporate users (yes, OpenIddict is used in enterprisey apps!).

OpenIddict 1.x and 2.x are here to stay (chances are high 1.x will be supported even after MSFT stops patching ASP.NET Core 1.0) so I prefer spending more time now than having regrets in a few months because the API we ended up with was not as good as I wanted. I’m sure you can understand that.

If you’re annoyed by the frequency of these changes, I suggest avoiding nightly builds (or even pre-release software in general).

[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.

[hoangdovan]

Yes, I see. Thanks!

On Fri, Apr 27, 2018, 8:52 PM Chino Chang [e-mail] wrote:

@hoangdovan https://github.com/hoangdovan as @PinpointTownes
https://github.com/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 without having a look at the release note for production
environment.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/openiddict/openiddict-core/issues/593#issuecomment-384976407,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AZPP_RX4g97n5HlBEkRpuw5d0vIBqt3Qks5tsyKSgaJpZM4TqHRN
.

[johnsanmiguel]

You are doing an awesome work! Keep it going!

I tried IdentityServer, but this was by far the simplest, I really like it.

Just want to ask, when are you planning to release this rc3 ? No pressure of course, thanks for your all your hard work.

[kevinchalet]

Hey @johnsanmiguel!

Thanks for the kind words (glad you like it!). I don't have a precise date yet, but I'd say later this month.

Cheers.

[xperiandri]

I like all the changes except ReplaceDefaultEntities.
They look extremely useful.