2018-01-22 00:06:22 +08:00
<!DOCTYPE html>
<!-- [if IE]><![endif] -->
< html >
< head >
< meta charset = "utf-8" >
< meta http-equiv = "X-UA-Compatible" content = "IE=edge,chrome=1" >
< title > Getting started < / title >
< meta name = "viewport" content = "width=device-width" >
< meta name = "title" content = "Getting started " >
< meta name = "generator" content = "docfx 2.24.0.0" >
< link rel = "shortcut icon" href = "../favicon.ico" >
< link rel = "stylesheet" href = "../styles/docfx.vendor.css" >
< link rel = "stylesheet" href = "../styles/docfx.css" >
< link rel = "stylesheet" href = "../styles/main.css" >
< meta property = "docfx:navrel" content = "../toc.html" >
< meta property = "docfx:tocrel" content = "toc.html" >
< / head >
< body data-spy = "scroll" data-target = "#affix" >
< div id = "wrapper" >
< header >
< nav id = "autocollapse" class = "navbar navbar-inverse ng-scope" role = "navigation" >
< div class = "container" >
< div class = "navbar-header" >
< button type = "button" class = "navbar-toggle" data-toggle = "collapse" data-target = "#navbar" >
< span class = "sr-only" > Toggle navigation< / span >
< span class = "icon-bar" > < / span >
< span class = "icon-bar" > < / span >
< span class = "icon-bar" > < / span >
< / button >
< a class = "navbar-brand" href = "../index.html" >
< img id = "logo" class = "svg" src = "../logo.svg" alt = "" >
< / a >
< / div >
< div class = "collapse navbar-collapse" id = "navbar" >
< form class = "navbar-form navbar-right" role = "search" id = "search" >
< div class = "form-group" >
< input type = "text" class = "form-control" id = "search-query" placeholder = "Search" autocomplete = "off" >
< / div >
< / form >
< / div >
< / div >
< / nav >
< div class = "subnav navbar navbar-default" >
< div class = "container hide-when-search" id = "breadcrumb" >
< ul class = "breadcrumb" >
< li > < / li >
< / ul >
< / div >
< / div >
< / header >
< div role = "main" class = "container body-content hide-when-search" >
< div class = "sidenav hide-when-search" >
< a class = "btn toc-toggle collapse" data-toggle = "collapse" href = "#sidetoggle" aria-expanded = "false" aria-controls = "sidetoggle" > Show / Hide Table of Contents< / a >
< div class = "sidetoggle collapse" id = "sidetoggle" >
< div id = "sidetoc" > < / div >
< / div >
< / div >
< div class = "article row grid-right" >
< div class = "col-md-10" >
< article class = "content wrap" id = "_content" data-uid = "" >
< h1 id = "getting-started" > Getting started< / h1 >
< p > To use OpenIddict, you need to:< / p >
< ul >
< li > < p > < strong > Install the latest < a href = "https://www.microsoft.com/net/download" > .NET Core 2.x tooling< / a > and update your packages to reference the ASP.NET Core 2.x packages< / strong > .< / p >
< / li >
< li > < p > < strong > Have an existing project or create a new one< / strong > : when creating a new project using Visual Studio' s default ASP.NET Core template, using < strong > individual user accounts authentication< / strong > is strongly recommended. When updating an existing project, you must provide your own < code > AccountController< / code > to handle the registration process and the authentication flow.< / p >
< / li >
2018-07-04 19:39:01 +08:00
< li > < p > < strong > Update your < code > .csproj< / code > file< / strong > to reference the < code > OpenIddict< / code > packages:< / p >
< pre > < code class = "lang-xml" > < PackageReference Include=" OpenIddict" Version=" 2.0.0-*" />
2018-01-22 00:06:22 +08:00
< PackageReference Include=" OpenIddict.EntityFrameworkCore" Version=" 2.0.0-*" />
< / code > < / pre > < / li >
< li > < p > < strong > Configure the OpenIddict services< / strong > in < code > Startup.ConfigureServices< / code > :< / p >
< pre > < code class = "lang-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.
2018-07-04 19:39:01 +08:00
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();
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
// Enable the token endpoint (required to use the password flow).
options.EnableTokenEndpoint(" /connect/token" );
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
// Allow client applications to use the grant_type=password flow.
options.AllowPasswordFlow();
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
// During development, you can disable the HTTPS requirement.
options.DisableHttpsRequirement();
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
// Accept token requests that don' t specify a client_id.
options.AcceptAnonymousClients();
})
.AddValidation();
2018-01-22 00:06:22 +08:00
}
2018-07-04 19:39:01 +08:00
< / code > < / pre > < / li >
2018-01-22 00:06:22 +08:00
< li > < p > < strong > Make sure the authentication middleware is registered before all the other middleware, including < code > app.UseMvc()< / code > < / strong > :< / p >
< pre > < code class = "lang-csharp" > public void Configure(IApplicationBuilder app)
{
app.UseAuthentication();
app.UseMvc();
}
< / code > < / pre > < / li >
< li > < p > < strong > Update your Entity Framework Core context registration to register the OpenIddict entities< / strong > :< / p >
< pre > < code class = "lang-csharp" > 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();
});
2018-07-04 19:39:01 +08:00
< / code > < / pre > < / li >
< / ul >
< blockquote > < p > < strong > Note:< / strong > if you change the default entity primary key (e.g. to < code > int< / code > or < code > Guid< / code > instead of < code > string< / code > ), make sure you use the < code > options.ReplaceDefaultEntities< TKey> ()< / code > core extension accepting a < code > TKey< / code > generic argument and use the generic < code > options.UseOpenIddict< TKey> ()< / code > overload to configure Entity Framework Core to use the specified key type:< / p >
< pre > < code class = "lang-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> ();
});
< / code > < / pre > < / blockquote >
< ul >
< li > < strong > Create your own authorization controller< / strong > :< / li >
< / ul >
2018-01-22 00:06:22 +08:00
< p > To < strong > support the password or the client credentials flow, you must provide your own token endpoint action< / strong > .
To enable authorization code/implicit flows support, you' ll similarly have to create your own authorization endpoint action and your own views/view models.< / p >
< p > The < strong > Mvc.Server sample comes with an < a href = "https://github.com/openiddict/openiddict-core/blob/dev/samples/Mvc.Server/Controllers/AuthorizationController.cs" > < code > AuthorizationController< / code > that supports both the password flow and the authorization code flow and that you can easily reuse in your application< / a > < / strong > .< / p >
2018-07-04 19:39:01 +08:00
< ul >
2018-01-22 00:06:22 +08:00
< li > < p > < strong > Enable the corresponding flows in the OpenIddict options< / strong > :< / p >
< pre > < code class = "lang-csharp" > public void ConfigureServices(IServiceCollection services)
{
// Register the OpenIddict services.
2018-07-04 19:39:01 +08:00
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();
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
// Enable the authorization/token endpoints (required to use the code flow).
options.EnableAuthorizationEndpoint(" /connect/authorize" )
.EnableTokenEndpoint(" /connect/token" );
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
// Allow client applications to use the code flow.
options.AllowAuthorizationCodeFlow();
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
// During development, you can disable the HTTPS requirement.
options.DisableHttpsRequirement();
})
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
.AddValidation();
2018-01-22 00:06:22 +08:00
}
< / code > < / pre > < / li >
< li > < p > < strong > Register your client application< / strong > :< / p >
2018-07-04 19:39:01 +08:00
< pre > < code class = "lang-csharp" > // Create a new service scope to ensure the database context
// is correctly disposed when this methods returns.
using (var scope = app.ApplicationServices.CreateScope())
2018-01-22 00:06:22 +08:00
{
2018-07-04 19:39:01 +08:00
var provider = scope.ServiceProvider;
var context = provider.GetRequiredService< ApplicationDbContext> ();
2018-01-22 00:06:22 +08:00
await context.Database.EnsureCreatedAsync();
2018-07-04 19:39:01 +08:00
var manager = provider.GetRequiredService< IOpenIddictApplicationManager> ();
2018-01-22 00:06:22 +08:00
2018-07-04 19:39:01 +08:00
if (await manager.FindByClientIdAsync(" [client identifier]" ) == null)
2018-01-22 00:06:22 +08:00
{
var descriptor = new OpenIddictApplicationDescriptor
{
ClientId = " [client identifier]" ,
ClientSecret = " [client secret]" ,
RedirectUris = { new Uri(" [redirect uri]" ) }
};
2018-07-04 19:39:01 +08:00
await manager.CreateAsync(descriptor);
2018-01-22 00:06:22 +08:00
}
}
< / code > < / pre > < / li >
< / ul >
< / article >
< / div >
< div class = "hidden-sm col-md-2" role = "complementary" >
< div class = "sideaffix" >
< div class = "contribution" >
< ul class = "nav" >
2018-07-04 19:22:23 +08:00
< li >
< a href = "https://github.com/openiddict/openiddict-documentation/blob/dev/guide/getting-started.md/#L1" class = "contribution-link" > Improve this Doc< / a >
< / li >
2018-01-22 00:06:22 +08:00
< / ul >
< / div >
< nav class = "bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id = "affix" >
<!-- <p><a class="back - to - top" href="#top">Back to top</a><p> -->
< / nav >
< / div >
< / div >
< / div >
< / div >
< footer >
< div class = "grad-bottom" > < / div >
< div class = "footer" >
< div class = "container" >
< span class = "pull-right" >
< a href = "#top" > Back to top< / a >
< / span >
< span > Copyright © 2015-2017 Microsoft< br > Generated by < strong > DocFX< / strong > < / span >
< / div >
< / div >
< / footer >
< / div >
< script type = "text/javascript" src = "../styles/docfx.vendor.js" > < / script >
< script type = "text/javascript" src = "../styles/docfx.js" > < / script >
< script type = "text/javascript" src = "../styles/main.js" > < / script >
< / body >
< / html >
