tsai
/
openiddict-core
mirror of https://github.com/openiddict/openiddict-core.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Update README.md to reference the OpenIddict 3.0 alpha packages

pull/844/head
Kévin Chalet 7 years ago
parent
4284800ecb
commit
6f2b9cddbb
2 changed files with 54 additions and 120 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 173
      README.md
  2. 1
      samples/Mvc.Server/Startup.cs

173
README.md
View File

@ -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
<PackageReference Include="OpenIddict" Version="2.0.0" />
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0" />
<PackageReference Include="OpenIddict.AspNetCore" Version="3.0.0-*" />
<PackageReference Include="OpenIddict.EntityFrameworkCore" Version="3.0.0-*" />
```
- **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<ApplicationDbContext>(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<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.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<ApplicationDbContext>();
})
// 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<ApplicationDbContext>(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<ApplicationDbContext>();
})
.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<IServiceScopeFactory>().CreateScope())
{
var context = scope.ServiceProvider.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>>();
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:

1
samples/Mvc.Server/Startup.cs
View File

@ -116,6 +116,7 @@ namespace Mvc.Server
// .IgnoreScopePermissions();
})
// Register the OpenIddict validation components.
.AddValidation(options =>
{
// Configure the audience accepted by this resource server.

Write Preview
Loading…
Cancel
Save