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.
- **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 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.EntityFrameworkCore" Version="2.0.0-*" />
<PackageReference Include="OpenIddict.Mvc" Version="2.0.0-*" />
```
- **Configure the OpenIddict services** in `Startup.ConfigureServices`:
@ -50,39 +36,39 @@ To use OpenIddict, you need to:
.AddEntityFrameworkStores<ApplicationDbContext>()
.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<ApplicationDbContext>();
services.AddOpenIddict()
.AddCore(options =>
{
// Configure OpenIddict to use the Entity Framework Core stores and entities.
options.UseEntityFrameworkCore()
.UseDbContext<ApplicationDbContext>();
})
// 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<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**:
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<ApplicationDbContext>();
services.AddOpenIddict()
.AddCore(options =>
{
// Configure OpenIddict to use the Entity Framework Core stores and entities.
options.UseEntityFrameworkCore()
.UseDbContext<ApplicationDbContext>();
})
// 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<IServiceScopeFactory>().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<ApplicationDbContext>();
var provider = scope.ServiceProvider;
var context = provider.GetRequiredService<ApplicationDbContext>();
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<OpenIddictApplicationManager<OpenIddictApplication>>();
var manager = provider.GetRequiredService<IOpenIddictApplicationManager>();
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);
}
}
```