OpenIddict

The OpenID Connect server you'll be addicted to.

Warning: this branch contains the OpenIddict 3.0 source code, which is still a work in progress. The 3.0.0 alpha packages haven't been heavily tested: don't use them in production. Nightly builds can be downloaded from the MyGet repository: https://www.myget.org/F/openiddict/api/v3/index.json

Compatibility matrix

What's OpenIddict?

OpenIddict aims at providing an easy-to-use and versatile solution to implement an OpenID Connect server in any ASP.NET Core 2.x or 3.x application, and starting in OpenIddict 3.0, any ASP.NET 4.x or OWIN application too.

OpenIddict fully supports the code/implicit/hybrid flows, the client credentials/resource owner password grants and the device authorization flow. You can also create your own custom grant types.

OpenIddict natively supports Entity Framework Core, Entity Framework 6 and MongoDB out-of-the-box, but you can also provide your own stores.

Why an OpenID Connect server?

Adding an OpenID Connect server to your application allows you to support token authentication. It also allows you to manage all your users using local password or an external identity provider (e.g. Facebook or Google) for all your applications in one central place, with the power to control who can access your API and the information that is exposed to each client.

Documentation

The documentation for the latest stable release (2.x) can be found in the dedicated repository.

Samples

Specialized samples for the latest stable release can be found in the samples repository:

• Authorization code flow sample
• Implicit flow sample
• Password flow sample
• Client credentials flow sample
• Refresh flow sample

Getting started

To use OpenIddict 3.x, you need to:

• Install the latest .NET Core 3.x tooling.

• Have an existing project or create a new one: when creating a new project using Visual Studio's default ASP.NET Core template, using individual user accounts authentication is strongly recommended. When updating an existing project, you must provide your own AccountController to handle the registration process and the authentication flow.

• Create a NuGet.config file referencing the OpenIddict feed (at the root of your solution):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
    <add key="openiddict" value="https://www.myget.org/F/openiddict/api/v3/index.json" />
  </packageSources>
</configuration>

• Update your .csproj file to reference the OpenIddict packages:

<PackageReference Include="OpenIddict.AspNetCore" Version="3.0.0-*" />
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="3.0.0-*" />

• Configure the OpenIddict core, server and validation services in Startup.ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
    services.AddOpenIddict()

        // Register the OpenIddict core components.
        .AddCore(options =>
        {
            // Configure OpenIddict to use the Entity Framework Core stores and models.
            options.UseEntityFrameworkCore()
                   .UseDbContext<ApplicationDbContext>();
        })

        // Register the OpenIddict server components.
        .AddServer(options =>
        {
            // Enable the token endpoint (required to use the password flow).
            options.SetTokenEndpointUris("/connect/token");

            // Allow client applications to use the grant_type=password flow.
            options.AllowPasswordFlow();

            // Accept requests sent by unknown clients (i.e that don't send a client_id).
            // When this option is not used, a client registration must be
            // created for each client using IOpenIddictApplicationManager.
            options.AcceptAnonymousClients();

            // Register the signing and encryption credentials.
            options.AddDevelopmentEncryptionCertificate()
                   .AddDevelopmentSigningCertificate();

            // Register the ASP.NET Core host and configure the ASP.NET Core-specific options.
            options.UseAspNetCore()
                   .EnableTokenEndpointPassthrough()
                   .DisableTransportSecurityRequirement(); // During development, you can disable the HTTPS requirement.
        })

        // Register the OpenIddict validation components.
        .AddValidation(options =>
        {
            // Import the configuration from the local OpenIddict server instance.
            options.UseLocalServer();

            // Register the ASP.NET Core host.
            options.UseAspNetCore();
        });
}

Note: for more information about the different options and configurations available, check out the documentation.

• Make sure the authentication middleware is registered before the other middleware, including app.UseEndpoints():

public void Configure(IApplicationBuilder app)
{
    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
        endpoints.MapRazorPages();
    });
}

• Update your Entity Framework Core context registration to register the OpenIddict entities:

services.AddDbContext<ApplicationDbContext>(options =>
{
    // Configure the context to use Microsoft SQL Server.
    options.UseSqlServer(Configuration["Data:DefaultConnection:ConnectionString"]);

    // Register the entity sets needed by OpenIddict.
    // Note: use the generic overload if you need
    // to replace the default OpenIddict entities.
    options.UseOpenIddict();
});

Note: if you change the default entity primary key (e.g. to int or Guid instead of string), make sure you use the options.ReplaceDefaultEntities<TKey>() core extension accepting a TKey generic argument and use the generic options.UseOpenIddict<TKey>() overload to configure Entity Framework Core to use the specified key type:

services.AddOpenIddict()
    .AddCore(options =>
    {
        // Configure OpenIddict to use the default entities with a custom key type.
        options.UseEntityFrameworkCore()
               .UseDbContext<ApplicationDbContext>()
               .ReplaceDefaultEntities<Guid>();
    });

services.AddDbContext<ApplicationDbContext>(options =>
{
    // Configure the context to use Microsoft SQL Server.
    options.UseSqlServer(configuration["Data:DefaultConnection:ConnectionString"]);

    options.UseOpenIddict<Guid>();
});

• Create your own authorization controller:

To support the password or the client credentials flow, you must provide your own token endpoint action. To enable authorization code/implicit flows support, you'll similarly have to create your own authorization endpoint action and your own views/view models.

The Mvc.Server sample comes with an AuthorizationController that supports both the password flow and the authorization code flow and that you can easily reuse in your application.

Resources

Looking for additional resources to help you get started with 3.x? Don't miss these interesting blog posts:

• Creating an OpenID Connect server proxy with OpenIddict 3.0's degraded mode by Kévin Chalet

Posts written for previous versions of OpenIddict:

• Setting up ASP.NET v5 (vNext) to use JWT tokens (using OpenIddict) by Sean Walsh
• Using OpenIddict to easily add token authentication to your .NET web apps by Josh Comley
• Authorizing your .NET Core MVC6 API requests with OpenIddict and Identity by Kerry Ritter
• Creating your own OpenID Connect server with ASOS by Kévin Chalet
• Bearer Token Authentication in ASP.NET Core by Mike Rousos (for the Microsoft .NET Web Development and Tools blog)
• Implementing simple token authentication in ASP.NET Core with OpenIddict by Kévin Chalet

Support

Need help or wanna share your thoughts? Don't hesitate to join us on Gitter or ask your question on StackOverflow:

• Gitter: https://gitter.im/openiddict/openiddict-core
• StackOverflow: https://stackoverflow.com/questions/tagged/openiddict

Contributors

OpenIddict is actively maintained by Kévin Chalet. Contributions are welcome and can be submitted using pull requests.

Special thanks to the following sponsors for their incredible support:

• David Hamilton from DAM Good Media
• Christopher McCrum from Data Citadel

License

This project is licensed under the Apache License. This means that you can use, modify and distribute it freely. See http://www.apache.org/licenses/LICENSE-2.0.html for more details.