diff --git a/README.md b/README.md index 92145787..4a7a035c 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,20 @@ # OpenIddict ### The OpenID Connect server you'll be addicted to. -[![Build status](https://ci.appveyor.com/api/projects/status/46ofo2eusje0hcw2?svg=true)](https://ci.appveyor.com/project/openiddict/openiddict-core) -[![Build status](https://travis-ci.org/openiddict/openiddict-core.svg)](https://travis-ci.org/openiddict/openiddict-core) +[![Build status](https://ci.appveyor.com/api/projects/status/46ofo2eusje0hcw2/branch/dev?svg=true)](https://ci.appveyor.com/project/openiddict/openiddict-core/branch/dev) +[![Build status](https://travis-ci.org/openiddict/openiddict-core.svg?branch=dev)](https://travis-ci.org/openiddict/openiddict-core) -> **Warning: this branch contains the OpenIddict 3.0 source code, which is still a work in progress**. +> **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 -> **The 3.0.0 alpha packages haven't been heavily tested: don't use them in production**. - ### What's OpenIddict? -OpenIddict aims at providing a **simple and easy-to-use solution** to implement an **OpenID Connect server in any ASP.NET Core 1.x or 2.x application**. - -OpenIddict is based on -**[AspNet.Security.OpenIdConnect.Server (codenamed ASOS)](https://github.com/aspnet-contrib/AspNet.Security.OpenIdConnect.Server)** to control the OpenID Connect authentication flow and can be used with any membership stack, **including [ASP.NET Core Identity](https://github.com/aspnet/Identity)**. +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](http://openid.net/specs/openid-connect-core-1_0.html)** and the **[client credentials/resource owner password grants](https://tools.ietf.org/html/rfc6749)**. You can also create your own custom grant types. +OpenIddict fully supports the **[code/implicit/hybrid flows](http://openid.net/specs/openid-connect-core-1_0.html)**, the **[client credentials/resource owner password grants](https://tools.ietf.org/html/rfc6749)** and the [device authorization flow](https://tools.ietf.org/html/rfc8628). You can also create your own custom grant types. -Note: OpenIddict natively supports **[Entity Framework Core](https://www.nuget.org/packages/OpenIddict.EntityFrameworkCore)**, **[Entity Framework 6](https://www.nuget.org/packages/OpenIddict.EntityFramework)** and **[MongoDB](https://www.nuget.org/packages/OpenIddict.MongoDb)** out-of-the-box, but you can also provide your own stores. - -> Note: **the OpenIddict 2.x packages are only compatible with ASP.NET Core 2.x**. -> If your application targets ASP.NET Core 1.x, use the OpenIddict 1.x packages. +OpenIddict natively supports **[Entity Framework Core](https://www.nuget.org/packages/OpenIddict.EntityFrameworkCore)**, **[Entity Framework 6](https://www.nuget.org/packages/OpenIddict.EntityFramework)** and **[MongoDB](https://www.nuget.org/packages/OpenIddict.MongoDb)** out-of-the-box, but you can also provide your own stores. ### Why an OpenID Connect server? @@ -32,11 +25,11 @@ with the power to control who can access your API and the information that is ex ## Documentation -**The documentation can be found in the [dedicated repository](https://openiddict.github.io/openiddict-documentation)**. +**The documentation for the latest stable release (2.x) can be found in the [dedicated repository](https://openiddict.github.io/openiddict-documentation)**. ## Samples -**[Specialized samples can be found in the samples repository](https://github.com/openiddict/openiddict-samples):** +**[Specialized samples for the latest stable release can be found in the samples repository](https://github.com/openiddict/openiddict-samples):** - [Authorization code flow sample](https://github.com/openiddict/openiddict-samples/tree/dev/samples/CodeFlow) - [Implicit flow sample](https://github.com/openiddict/openiddict-samples/tree/dev/samples/ImplicitFlow) @@ -44,92 +37,94 @@ with the power to control who can access your API and the information that is ex - [Client credentials flow sample](https://github.com/openiddict/openiddict-samples/tree/dev/samples/ClientCredentialsFlow) - [Refresh flow sample](https://github.com/openiddict/openiddict-samples/tree/dev/samples/RefreshFlow) -> **Samples for ASP.NET Core 1.x can be found [in the master branch of the samples repository](https://github.com/openiddict/openiddict-samples/tree/master)**. -------------- ## Getting started -To use OpenIddict, you need to: +To use OpenIddict 3.x, you need to: - - **Install the latest [.NET Core 2.x tooling](https://www.microsoft.com/net/download) and update your packages to reference the ASP.NET Core 2.x packages**. + - **Install the latest [.NET Core 3.x tooling](https://www.microsoft.com/net/download)**. - **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. - **Update your `.csproj` file** to reference the `OpenIddict` packages: ```xml - - + + ``` - - **Configure the OpenIddict services** in `Startup.ConfigureServices`: + - **Configure the OpenIddict core, server and validation services** in `Startup.ConfigureServices`: ```csharp public void ConfigureServices(IServiceCollection services) { - services.AddMvc(); - - services.AddDbContext(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(); - }); - - // Register the Identity services. - services.AddIdentity() - .AddEntityFrameworkStores() - .AddDefaultTokenProviders(); - - // Register the OpenIddict services. services.AddOpenIddict() + + // Register the OpenIddict core components. .AddCore(options => { - // Configure OpenIddict to use the Entity Framework Core stores and entities. + // Configure OpenIddict to use the Entity Framework Core stores and models. options.UseEntityFrameworkCore() .UseDbContext(); }) + // Register the OpenIddict server components. .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 token endpoint (required to use the password flow). - options.EnableTokenEndpoint("/connect/token"); + options.SetTokenEndpointUris("/connect/token"); // Allow client applications to use the grant_type=password flow. options.AllowPasswordFlow(); - // During development, you can disable the HTTPS requirement. - options.DisableHttpsRequirement(); - - // Accept token requests that don't specify a client_id. + // 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. }) - .AddValidation(); + // 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 -[Configuration and options](https://github.com/openiddict/core/wiki/Configuration-and-options) -in the project wiki. +[the documentation](https://openiddict.github.io/openiddict-documentation/configuration/index.html). - - **Make sure the authentication middleware is registered before all the other middleware, including `app.UseMvc()`**: + - **Make sure the authentication middleware is registered before the other middleware, including `app.UseEndpoints()`**: ```csharp public void Configure(IApplicationBuilder app) { + app.UseRouting(); + app.UseAuthentication(); + app.UseAuthorization(); - app.UseMvc(); + app.UseEndpoints(endpoints => + { + endpoints.MapControllerRoute( + name: "default", + pattern: "{controller=Home}/{action=Index}/{id?}"); + endpoints.MapRazorPages(); + }); } ``` @@ -139,7 +134,7 @@ public void Configure(IApplicationBuilder app) services.AddDbContext(options => { // Configure the context to use Microsoft SQL Server. - options.UseSqlServer(configuration["Data:DefaultConnection:ConnectionString"]); + options.UseSqlServer(Configuration["Data:DefaultConnection:ConnectionString"]); // Register the entity sets needed by OpenIddict. // Note: use the generic overload if you need @@ -177,68 +172,6 @@ To enable authorization code/implicit flows support, you'll similarly have to cr 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](https://github.com/openiddict/openiddict-core/blob/dev/samples/Mvc.Server/Controllers/AuthorizationController.cs)**. - - **Enable the corresponding flows in the OpenIddict options**: - -```csharp -public void ConfigureServices(IServiceCollection services) -{ - // Register the OpenIddict services. - services.AddOpenIddict() - .AddCore(options => - { - // Configure OpenIddict to use the Entity Framework Core stores and entities. - options.UseEntityFrameworkCore() - .UseDbContext(); - }) - - .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 and token endpoints (required to use the code flow). - options.EnableAuthorizationEndpoint("/connect/authorize") - .EnableTokenEndpoint("/connect/token"); - - // Allow client applications to use the code flow. - options.AllowAuthorizationCodeFlow(); - - // During development, you can disable the HTTPS requirement. - options.DisableHttpsRequirement(); - }) - - .AddValidation(); -} -``` - - - **Register your client application**: - -```csharp -// Create a new service scope to ensure the database context is correctly disposed when this methods returns. -using (var scope = app.ApplicationServices.GetRequiredService().CreateScope()) -{ - var context = scope.ServiceProvider.GetRequiredService(); - await context.Database.EnsureCreatedAsync(); - - // Note: when using a custom entity or a custom key type, replace OpenIddictApplication by the appropriate type. - var manager = scope.ServiceProvider.GetRequiredService>(); - - if (await manager.FindByClientIdAsync("[client identifier]", cancellationToken) == null) - { - var descriptor = new OpenIddictApplicationDescriptor - { - ClientId = "[client identifier]", - ClientSecret = "[client secret]", - RedirectUris = { new Uri("[redirect uri]") } - }; - - await manager.CreateAsync(descriptor, cancellationToken); - } -} -``` - ## Resources **Looking for additional resources to help you get started?** Don't miss these interesting blog posts/books: diff --git a/samples/Mvc.Server/Startup.cs b/samples/Mvc.Server/Startup.cs index a25fa52c..c915e075 100644 --- a/samples/Mvc.Server/Startup.cs +++ b/samples/Mvc.Server/Startup.cs @@ -116,6 +116,7 @@ namespace Mvc.Server // .IgnoreScopePermissions(); }) + // Register the OpenIddict validation components. .AddValidation(options => { // Configure the audience accepted by this resource server.