diff --git a/guide/getting-started.md b/guide/getting-started.md index 5151794..347c8cd 100644 --- a/guide/getting-started.md +++ b/guide/getting-started.md @@ -6,25 +6,11 @@ To use OpenIddict, you need to: - **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. - - **Add the appropriate MyGet repositories to your NuGet sources**. This can be done by adding a new `NuGet.Config` file at the root of your solution: + - **Update your `.csproj` file** to reference the `OpenIddict` packages: ```xml - - - - - - - - ``` - - - **Update your `.csproj` file** to reference `AspNet.Security.OAuth.Validation` and the `OpenIddict` packages: - - ```xml - - ``` - **Configure the OpenIddict services** in `Startup.ConfigureServices`: @@ -50,39 +36,39 @@ To use OpenIddict, you need to: .AddEntityFrameworkStores() .AddDefaultTokenProviders(); - // Register the OAuth2 validation handler. - services.AddAuthentication() - .AddOAuthValidation(); - // Register the OpenIddict services. - // Note: use the generic overload if you need - // to replace the default OpenIddict entities. - services.AddOpenIddict(options => - { - // Register the Entity Framework stores. - options.AddEntityFrameworkCoreStores(); + services.AddOpenIddict() + .AddCore(options => + { + // Configure OpenIddict to use the Entity Framework Core stores and entities. + options.UseEntityFrameworkCore() + .UseDbContext(); + }) - // 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.AddMvcBinders(); + .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"); + // Enable the token endpoint (required to use the password flow). + options.EnableTokenEndpoint("/connect/token"); - // Allow client applications to use the grant_type=password flow. - options.AllowPasswordFlow(); + // Allow client applications to use the grant_type=password flow. + options.AllowPasswordFlow(); - // During development, you can disable the HTTPS requirement. - options.DisableHttpsRequirement(); - }); + // During development, you can disable the HTTPS requirement. + options.DisableHttpsRequirement(); + + // Accept token requests that don't specify a client_id. + options.AcceptAnonymousClients(); + }) + + .AddValidation(); } ``` - > **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. - - **Make sure the authentication middleware is registered before all the other middleware, including `app.UseMvc()`**: ```csharp @@ -109,14 +95,33 @@ To use OpenIddict, you need to: }); ``` - > **Note:** if you change the default entity primary key (e.g. to `int` or `Guid` instead of `string`), make sure to use the `services.AddOpenIddict()` extension accepting a `TKey` generic argument and use the generic `options.UseOpenIddict()` overload. +> **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()` core extension accepting a `TKey` generic argument and use the generic `options.UseOpenIddict()` overload to configure Entity Framework Core to use the specified key type: +> +> ```csharp +> services.AddOpenIddict() +> .AddCore(options => +> { +> // Configure OpenIddict to use the default entities with a custom key type. +> options.UseEntityFrameworkCore() +> .UseDbContext() +> .ReplaceDefaultEntities(); +> }); +> +> services.AddDbContext(options => +> { +> // Configure the context to use Microsoft SQL Server. +> options.UseSqlServer(configuration["Data:DefaultConnection:ConnectionString"]); +> +> options.UseOpenIddict(); +> }); +>``` - **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. +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](https://github.com/openiddict/openiddict-core/blob/dev/samples/Mvc.Server/Controllers/AuthorizationController.cs)**. +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**: @@ -124,44 +129,50 @@ To use OpenIddict, you need to: public void ConfigureServices(IServiceCollection services) { // Register the OpenIddict services. - // Note: use the generic overload if you need - // to replace the default OpenIddict entities. - services.AddOpenIddict(options => - { - // Register the Entity Framework stores. - options.AddEntityFrameworkCoreStores(); + services.AddOpenIddict() + .AddCore(options => + { + // Configure OpenIddict to use the Entity Framework Core stores and entities. + options.UseEntityFrameworkCore() + .UseDbContext(); + }) - // 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.AddMvcBinders(); + .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"); + // Enable the authorization/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(); + // Allow client applications to use the code flow. + options.AllowAuthorizationCodeFlow(); - // During development, you can disable the HTTPS requirement. - options.DisableHttpsRequirement(); - }); + // 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()) + // Create a new service scope to ensure the database context + // is correctly disposed when this methods returns. + using (var scope = app.ApplicationServices.CreateScope()) { - var context = scope.ServiceProvider.GetRequiredService(); + var provider = scope.ServiceProvider; + var context = provider.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>(); + var manager = provider.GetRequiredService(); - if (await manager.FindByClientIdAsync("[client identifier]", cancellationToken) == null) + if (await manager.FindByClientIdAsync("[client identifier]") == null) { var descriptor = new OpenIddictApplicationDescriptor { @@ -170,7 +181,7 @@ To use OpenIddict, you need to: RedirectUris = { new Uri("[redirect uri]") } }; - await manager.CreateAsync(descriptor, cancellationToken); + await manager.CreateAsync(descriptor); } } ``` \ No newline at end of file