lsm/openiddict-documentation
1
0
Fork 0
mirror of https://gitee.com/dcren/openiddict-documentation.git synced 2026-01-02 04:17:09 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update the getting started page

Browse Source
This commit is contained in:
Kévin Chalet
2021-01-13 05:48:11 +01:00
parent 9db89d9f43
commit d8e71e3976
4 changed files with 145 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
configuration/application-permissions.md
View File

@@ -198,7 +198,7 @@ services.AddOpenIddict()
## Response type permissions ## Response type permissions
-> [!NOTE] > [!NOTE]
> Response type permissions were introduced in OpenIddict 3.0. > Response type permissions were introduced in OpenIddict 3.0.
### Definition ### Definition

259
guide/getting-started.md
View File

@@ -1,44 +1,33 @@
# Getting started # Getting started
To use OpenIddict, you need to: **To implement a custom OpenID Connect server using OpenIddict, the simplest option is to clone one of the official samples** from the [openiddict-samples repository](https://github.com/openiddict/openiddict-samples).
- **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**. If you don't want to start from one of the recommended samples, you'll 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. - **Install the [.NET Core 2.1.x, 3.1.x or .NET 5.0.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 as it automatically includes the default ASP.NET Core Identity UI, based on Razor Pages.
- **Update your `.csproj` file** to reference the `OpenIddict` packages: - **Update your `.csproj` file** to reference the `OpenIddict` packages:
```xml ```xml
<PackageReference Include="OpenIddict" Version="2.0.0-*" /> <PackageReference Include="OpenIddict.AspNetCore" Version="3.0.0" />
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-*" /> <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="3.0.0" />
``` ```
- **OPTIONAL: If you want to try out the latest features and bug fixes,** there is a MyGet feed with nightly builds - **Configure the OpenIddict core, server and validation services** in `Startup.ConfigureServices`.
of OpenIddict. Here's an example for the client credentials grant, used in machine-to-machine scenarios:
To reference the OpenIddict MyGet feed, **create a `NuGet.config` file** (at the root of your solution):
```xml
<?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>
```
- **Configure the OpenIddict services** in `Startup.ConfigureServices`:
```csharp ```csharp
public void ConfigureServices(IServiceCollection services) public void ConfigureServices(IServiceCollection services)
{ {
services.AddMvc(); services.AddControllersWithViews();
services.AddDbContext<ApplicationDbContext>(options => services.AddDbContext<ApplicationDbContext>(options =>
{ {
// Configure the context to use Microsoft SQL Server. // Configure the context to use Microsoft SQL Server.
options.UseSqlServer(configuration["Data:DefaultConnection:ConnectionString"]); options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"));
// Register the entity sets needed by OpenIddict. // Register the entity sets needed by OpenIddict.
// Note: use the generic overload if you need // Note: use the generic overload if you need
@@ -46,52 +35,70 @@ To use OpenIddict, you need to:
options.UseOpenIddict(); options.UseOpenIddict();
}); });
// Register the Identity services.
services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();
// Register the OpenIddict services.
services.AddOpenIddict() services.AddOpenIddict()
// Register the OpenIddict core components.
.AddCore(options => .AddCore(options =>
{ {
// Configure OpenIddict to use the Entity Framework Core stores and entities. // Configure OpenIddict to use the Entity Framework Core stores and models.
// Note: call ReplaceDefaultEntities() to replace the default entities.
options.UseEntityFrameworkCore() options.UseEntityFrameworkCore()
.UseDbContext<ApplicationDbContext>(); .UseDbContext<ApplicationDbContext>();
}) })
// Register the OpenIddict server components.
.AddServer(options => .AddServer(options =>
{ {
// Register the ASP.NET Core MVC binder used by OpenIddict. // Enable the token endpoint.
// Note: if you don't call this method, you won't be able to options.SetTokenEndpointUris("/connect/token");
// bind OpenIdConnectRequest or OpenIdConnectResponse parameters.
options.UseMvc();
// Enable the token endpoint (required to use the password flow). // Enable the client credentials flow.
options.EnableTokenEndpoint("/connect/token"); options.AllowClientCredentialsFlow();
// Allow client applications to use the grant_type=password flow. // Register the signing and encryption credentials.
options.AllowPasswordFlow(); options.AddDevelopmentEncryptionCertificate()
.AddDevelopmentSigningCertificate();
// During development, you can disable the HTTPS requirement. // Register the ASP.NET Core host and configure the ASP.NET Core options.
options.DisableHttpsRequirement(); options.UseAspNetCore()
.EnableTokenEndpointPassthrough();
// Accept token requests that don't specify a client_id.
options.AcceptAnonymousClients();
}) })
.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();
});
// Register the worker responsible of seeding the database with the sample clients.
// Note: in a real world application, this step should be part of a setup script.
services.AddHostedService<Worker>();
} }
``` ```
- **Make sure the authentication middleware is registered before all the other middleware, including `app.UseMvc()`**: - **Make sure the ASP.NET Core authentication middleware is correctly registered at the right place**:
```csharp ```csharp
public void Configure(IApplicationBuilder app) public void Configure(IApplicationBuilder app)
{ {
app.UseAuthentication(); app.UseDeveloperExceptionPage();
app.UseMvc(); app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(options =>
{
options.MapControllers();
options.MapDefaultControllerRoute();
});
app.UseWelcomePage();
} }
``` ```
@@ -101,7 +108,7 @@ To use OpenIddict, you need to:
services.AddDbContext<ApplicationDbContext>(options => services.AddDbContext<ApplicationDbContext>(options =>
{ {
// Configure the context to use Microsoft SQL Server. // Configure the context to use Microsoft SQL Server.
options.UseSqlServer(configuration["Data:DefaultConnection:ConnectionString"]); options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"));
// Register the entity sets needed by OpenIddict. // Register the entity sets needed by OpenIddict.
// Note: use the generic overload if you need // Note: use the generic overload if you need
@@ -110,93 +117,115 @@ 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 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: > [!WARNING]
> > Important: 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>()`
> ```csharp > core extension accepting a `TKey` generic argument and use the generic `options.UseOpenIddict<TKey>()` overload to configure EF Core to use the specified type:
> services.AddOpenIddict() >
> .AddCore(options => > ```csharp
> { > services.AddOpenIddict()
> // Configure OpenIddict to use the default entities with a custom key type. > .AddCore(options =>
> options.UseEntityFrameworkCore() > {
> .UseDbContext<ApplicationDbContext>() > // Configure OpenIddict to use the default entities with a custom key type.
> .ReplaceDefaultEntities<Guid>(); > options.UseEntityFrameworkCore()
> }); > .UseDbContext<ApplicationDbContext>()
> > .ReplaceDefaultEntities<Guid>();
> services.AddDbContext<ApplicationDbContext>(options => > });
> { >
> // Configure the context to use Microsoft SQL Server. > services.AddDbContext<ApplicationDbContext>(options =>
> options.UseSqlServer(configuration["Data:DefaultConnection:ConnectionString"]); > {
> > // Configure the context to use Microsoft SQL Server.
> options.UseOpenIddict<Guid>(); > options.UseSqlServer(configuration["Data:DefaultConnection:ConnectionString"]);
> }); >
>``` > options.UseOpenIddict<Guid>();
> });
>```
- **Create your own authorization controller**: - **Create your own authorization controller:**
Implementing a custom authorization controller is required to allow OpenIddict to create tokens based on the identities and claims you provide.
To **support the password or the client credentials flow, you must provide your own token endpoint action**. Here's an example for the client credentials grant:
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)**.
- **Enable the corresponding flows in the OpenIddict options**:
```csharp ```csharp
public void ConfigureServices(IServiceCollection services) public class AuthorizationController : Controller
{ {
// Register the OpenIddict services. private readonly IOpenIddictApplicationManager_applicationManager;
services.AddOpenIddict()
.AddCore(options => public AuthorizationController(IOpenIddictApplicationManager applicationManager)
=> _applicationManager = applicationManager;
[HttpPost("~/connect/token"), Produces("application/json")]
public async Task<IActionResult> Exchange()
{
var request = HttpContext.GetOpenIddictServerRequest();
if (!request.IsClientCredentialsGrantType())
{ {
// Configure OpenIddict to use the Entity Framework Core stores and entities. throw new NotImplementedException("The specified grant is not implemented.");
options.UseEntityFrameworkCore() }
.UseDbContext<ApplicationDbContext>();
})
.AddServer(options => // Note: the client credentials are automatically validated by OpenIddict:
{ // if client_id or client_secret are invalid, this action won't be invoked.
// 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/token endpoints (required to use the code flow). var application =
options.EnableAuthorizationEndpoint("/connect/authorize") await _applicationManager.FindByClientIdAsync(request.ClientId) ??
.EnableTokenEndpoint("/connect/token"); throw new InvalidOperationException("The application cannot be found.");
// Allow client applications to use the code flow. // Create a new ClaimsIdentity containing the claims that
options.AllowAuthorizationCodeFlow(); // will be used to create an id_token, a token or a code.
var identity = new ClaimsIdentity(
TokenValidationParameters.DefaultAuthenticationType,
Claims.Name, Claims.Role);
// During development, you can disable the HTTPS requirement. // Use the client_id as the subject identifier.
options.DisableHttpsRequirement(); identity.AddClaim(Claims.Subject,
}) await _applicationManager.GetClientIdAsync(application),
Destinations.AccessToken, Destinations.IdentityToken);
.AddValidation(); identity.AddClaim(Claims.Name,
await _applicationManager.GetDisplayNameAsync(application),
Destinations.AccessToken, Destinations.IdentityToken);
return SignIn(new ClaimsPrincipal(identity),
OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);
}
} }
``` ```
- **Register your client application**: - **Register your client application** (e.g from an `IHostedService` implementation):
```csharp ```csharp
// Create a new service scope to ensure the database context public class Worker : IHostedService
// is correctly disposed when this methods returns.
using (var scope = app.ApplicationServices.CreateScope())
{ {
var provider = scope.ServiceProvider; private readonly IServiceProvider _serviceProvider;
var context = provider.GetRequiredService<ApplicationDbContext>();
await context.Database.EnsureCreatedAsync();
var manager = provider.GetRequiredService<IOpenIddictApplicationManager>(); public Worker(IServiceProvider serviceProvider)
=> _serviceProvider = serviceProvider;
if (await manager.FindByClientIdAsync("[client identifier]") == null) public async Task StartAsync(CancellationToken cancellationToken)
{ {
var descriptor = new OpenIddictApplicationDescriptor using var scope = _serviceProvider.CreateScope();
{
ClientId = "[client identifier]",
ClientSecret = "[client secret]",
RedirectUris = { new Uri("[redirect uri]") }
};
await manager.CreateAsync(descriptor); var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
await context.Database.EnsureCreatedAsync();
var manager =
scope.ServiceProvider.GetRequiredService<IOpenIddictApplicationManager>();
if (await manager.FindByClientIdAsync("console") is null)
{
await manager.CreateAsync(new OpenIddictApplicationDescriptor
{
ClientId = "console",
ClientSecret = "388D45FA-B36B-4988-BA59-B187D329C207",
DisplayName = "My client application",
Permissions =
{
Permissions.Endpoints.Token,
Permissions.GrantTypes.ClientCredentials
}
});
}
} }
public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
} }
``` ```

11
guide/samples.md
View File

@@ -1,11 +0,0 @@
# Samples
**[Specialized samples 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)
- [Password flow sample](https://github.com/openiddict/openiddict-samples/tree/dev/samples/PasswordFlow)
- [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)**.

3
guide/toc.yml
View File

@@ -4,8 +4,5 @@
- name: Getting started - name: Getting started
href: getting-started.md href: getting-started.md
- name: Samples
href: samples.md
- name: Migration guide - name: Migration guide
href: migration.md href: migration.md