lsm/openiddict-documentation
1
0
Fork 0
mirror of https://gitee.com/dcren/openiddict-documentation.git synced 2025-07-15 23:13:34 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update the getting started page to use the new OpenIddict RC3 APIs

Browse Source
This commit is contained in:
Kévin Chalet 2018-07-04 13:36:01 +02:00
parent 222a8c1694
commit 9831c32d06
1 changed files with 80 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
guide/getting-started.md
View File

@ -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. - **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 ```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="NuGet" value="https://api.nuget.org/v3/index.json" />
<add key="aspnet-contrib" value="https://www.myget.org/F/aspnet-contrib/api/v3/index.json" />
</packageSources>
</configuration>
```
- **Update your `.csproj` file** to reference `AspNet.Security.OAuth.Validation` and the `OpenIddict` packages:
```xml
<PackageReference Include="AspNet.Security.OAuth.Validation" Version="2.0.0-*" />
<PackageReference Include="OpenIddict" Version="2.0.0-*" /> <PackageReference Include="OpenIddict" Version="2.0.0-*" />
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-*" /> <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-*" />
<PackageReference Include="OpenIddict.Mvc" Version="2.0.0-*" />
``` ```
- **Configure the OpenIddict services** in `Startup.ConfigureServices`: - **Configure the OpenIddict services** in `Startup.ConfigureServices`:
@ -50,39 +36,39 @@ To use OpenIddict, you need to:
.AddEntityFrameworkStores<ApplicationDbContext>() .AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders(); .AddDefaultTokenProviders();
// Register the OAuth2 validation handler.
services.AddAuthentication()
.AddOAuthValidation();
// Register the OpenIddict services. // Register the OpenIddict services.
// Note: use the generic overload if you need services.AddOpenIddict()
// to replace the default OpenIddict entities. .AddCore(options =>
services.AddOpenIddict(options => {
{ // Configure OpenIddict to use the Entity Framework Core stores and entities.
// Register the Entity Framework stores. options.UseEntityFrameworkCore()
options.AddEntityFrameworkCoreStores<ApplicationDbContext>(); .UseDbContext<ApplicationDbContext>();
})
// Register the ASP.NET Core MVC binder used by OpenIddict. .AddServer(options =>
// Note: if you don't call this method, you won't be able to {
// bind OpenIdConnectRequest or OpenIdConnectResponse parameters. // Register the ASP.NET Core MVC binder used by OpenIddict.
options.AddMvcBinders(); // 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). // Enable the token endpoint (required to use the password flow).
options.EnableTokenEndpoint("/connect/token"); options.EnableTokenEndpoint("/connect/token");
// Allow client applications to use the grant_type=password flow. // Allow client applications to use the grant_type=password flow.
options.AllowPasswordFlow(); options.AllowPasswordFlow();
// During development, you can disable the HTTPS requirement. // During development, you can disable the HTTPS requirement.
options.DisableHttpsRequirement(); 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()`**: - **Make sure the authentication middleware is registered before all the other middleware, including `app.UseMvc()`**:
```csharp ```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<TKey>()` 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<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:
>
> ```csharp
> 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**: - **Create your own authorization controller**:
To **support the password or the client credentials flow, you must provide your own token endpoint action**. 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 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**: - **Enable the corresponding flows in the OpenIddict options**:
@ -124,44 +129,50 @@ To use OpenIddict, you need to:
public void ConfigureServices(IServiceCollection services) public void ConfigureServices(IServiceCollection services)
{ {
// Register the OpenIddict services. // Register the OpenIddict services.
// Note: use the generic overload if you need services.AddOpenIddict()
// to replace the default OpenIddict entities. .AddCore(options =>
services.AddOpenIddict(options => {
{ // Configure OpenIddict to use the Entity Framework Core stores and entities.
// Register the Entity Framework stores. options.UseEntityFrameworkCore()
options.AddEntityFrameworkCoreStores<ApplicationDbContext>(); .UseDbContext<ApplicationDbContext>();
})
// Register the ASP.NET Core MVC binder used by OpenIddict. .AddServer(options =>
// Note: if you don't call this method, you won't be able to {
// bind OpenIdConnectRequest or OpenIdConnectResponse parameters. // Register the ASP.NET Core MVC binder used by OpenIddict.
options.AddMvcBinders(); // 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). // Enable the authorization/token endpoints (required to use the code flow).
options.EnableAuthorizationEndpoint("/connect/authorize") options.EnableAuthorizationEndpoint("/connect/authorize")
.EnableTokenEndpoint("/connect/token"); .EnableTokenEndpoint("/connect/token");
// Allow client applications to use the code flow. // Allow client applications to use the code flow.
options.AllowAuthorizationCodeFlow(); options.AllowAuthorizationCodeFlow();
// During development, you can disable the HTTPS requirement. // During development, you can disable the HTTPS requirement.
options.DisableHttpsRequirement(); options.DisableHttpsRequirement();
}); })
.AddValidation();
} }
``` ```
- **Register your client application**: - **Register your client application**:
```csharp ```csharp
// Create a new service scope to ensure the database context is correctly disposed when this methods returns. // Create a new service scope to ensure the database context
using (var scope = app.ApplicationServices.GetRequiredService<IServiceScopeFactory>().CreateScope()) // is correctly disposed when this methods returns.
using (var scope = app.ApplicationServices.CreateScope())
{ {
var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>(); var provider = scope.ServiceProvider;
var context = provider.GetRequiredService<ApplicationDbContext>();
await context.Database.EnsureCreatedAsync(); await context.Database.EnsureCreatedAsync();
// Note: when using a custom entity or a custom key type, replace OpenIddictApplication by the appropriate type. var manager = provider.GetRequiredService<IOpenIddictApplicationManager>();
var manager = scope.ServiceProvider.GetRequiredService<OpenIddictApplicationManager<OpenIddictApplication>>();
if (await manager.FindByClientIdAsync("[client identifier]", cancellationToken) == null) if (await manager.FindByClientIdAsync("[client identifier]") == null)
{ {
var descriptor = new OpenIddictApplicationDescriptor var descriptor = new OpenIddictApplicationDescriptor
{ {
@ -170,7 +181,7 @@ To use OpenIddict, you need to:
RedirectUris = { new Uri("[redirect uri]") } RedirectUris = { new Uri("[redirect uri]") }
}; };
await manager.CreateAsync(descriptor, cancellationToken); await manager.CreateAsync(descriptor);
} }
} }
``` ```