Update the documentation pages

This commit is contained in:
OpenIddict Bot 2021-01-13 04:49:17 +00:00
parent 1b112c1099
commit c24ded39ce
5 changed files with 130 additions and 232 deletions

View File

@ -68,36 +68,28 @@
<article class="content wrap" id="_content" data-uid="">
<h1 id="getting-started">Getting started</h1>
<p>To use OpenIddict, you need to:</p>
<p><strong>To implement a custom OpenID Connect server using OpenIddict, the simplest option is to clone one of the official samples</strong> from the <a href="https://github.com/openiddict/openiddict-samples">openiddict-samples repository</a>.</p>
<p>If you don&#39;t want to start from one of the recommended samples, you&#39;ll 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><p><strong>Install the <a href="https://www.microsoft.com/net/download">.NET Core 2.1.x, 3.1.x or .NET 5.0.x tooling</a></strong>.</p>
</li>
<li><p><strong>Have an existing project or create a new one</strong>: when creating a new project using Visual Studio&#39;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><p><strong>Have an existing project or create a new one</strong>: when creating a new project using Visual Studio&#39;s default ASP.NET Core template,
using <strong>individual user accounts authentication</strong> is strongly recommended as it automatically includes the default ASP.NET Core Identity UI, based on Razor Pages.</p>
</li>
<li><p><strong>Update your <code>.csproj</code> file</strong> to reference the <code>OpenIddict</code> packages:</p>
<pre><code class="lang-xml">&lt;PackageReference Include=&quot;OpenIddict&quot; Version=&quot;2.0.0-*&quot; /&gt;
&lt;PackageReference Include=&quot;OpenIddict.EntityFrameworkCore&quot; Version=&quot;2.0.0-*&quot; /&gt;
<pre><code class="lang-xml">&lt;PackageReference Include=&quot;OpenIddict.AspNetCore&quot; Version=&quot;3.0.0&quot; /&gt;
&lt;PackageReference Include=&quot;OpenIddict.EntityFrameworkCore&quot; Version=&quot;3.0.0&quot; /&gt;
</code></pre></li>
<li><p><strong>OPTIONAL: If you want to try out the latest features and bug fixes,</strong> there is a MyGet feed with nightly builds
of OpenIddict.</p>
<p>To reference the OpenIddict MyGet feed, <strong>create a <code>NuGet.config</code> file</strong> (at the root of your solution):</p>
<pre><code class="lang-xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;configuration&gt;
&lt;packageSources&gt;
&lt;add key=&quot;nuget&quot; value=&quot;https://api.nuget.org/v3/index.json&quot; /&gt;
&lt;add key=&quot;openiddict&quot; value=&quot;https://www.myget.org/F/openiddict/api/v3/index.json&quot; /&gt;
&lt;/packageSources&gt;
&lt;/configuration&gt;
</code></pre></li>
<li><p><strong>Configure the OpenIddict services</strong> in <code>Startup.ConfigureServices</code>:</p>
<li><p><strong>Configure the OpenIddict core, server and validation services</strong> in <code>Startup.ConfigureServices</code>.
Here&#39;s an example for the client credentials grant, used in machine-to-machine scenarios:</p>
<pre><code class="lang-csharp">public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddControllersWithViews();
services.AddDbContext&lt;ApplicationDbContext&gt;(options =&gt;
{
// Configure the context to use Microsoft SQL Server.
options.UseSqlServer(configuration[&quot;Data:DefaultConnection:ConnectionString&quot;]);
options.UseSqlServer(Configuration.GetConnectionString(&quot;DefaultConnection&quot;));
// Register the entity sets needed by OpenIddict.
// Note: use the generic overload if you need
@ -105,56 +97,74 @@ of OpenIddict.</p>
options.UseOpenIddict();
});
// Register the Identity services.
services.AddIdentity&lt;ApplicationUser, IdentityRole&gt;()
.AddEntityFrameworkStores&lt;ApplicationDbContext&gt;()
.AddDefaultTokenProviders();
// Register the OpenIddict services.
services.AddOpenIddict()
// Register the OpenIddict core components.
.AddCore(options =&gt;
{
// 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 OpenIddict entities.
options.UseEntityFrameworkCore()
.UseDbContext&lt;ApplicationDbContext&gt;();
})
// Register the OpenIddict server components.
.AddServer(options =&gt;
{
// Register the ASP.NET Core MVC binder used by OpenIddict.
// Note: if you don&#39;t call this method, you won&#39;t be able to
// bind OpenIdConnectRequest or OpenIdConnectResponse parameters.
options.UseMvc();
// Enable the token endpoint.
options.SetTokenEndpointUris(&quot;/connect/token&quot;);
// Enable the token endpoint (required to use the password flow).
options.EnableTokenEndpoint(&quot;/connect/token&quot;);
// Enable the client credentials flow.
options.AllowClientCredentialsFlow();
// Allow client applications to use the grant_type=password flow.
options.AllowPasswordFlow();
// Register the signing and encryption credentials.
options.AddDevelopmentEncryptionCertificate()
.AddDevelopmentSigningCertificate();
// During development, you can disable the HTTPS requirement.
options.DisableHttpsRequirement();
// Accept token requests that don&#39;t specify a client_id.
options.AcceptAnonymousClients();
// Register the ASP.NET Core host and configure the ASP.NET Core-specific options.
options.UseAspNetCore()
.EnableTokenEndpointPassthrough();
})
.AddValidation();
// Register the OpenIddict validation components.
.AddValidation(options =&gt;
{
// 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&lt;Worker&gt;();
}
</code></pre></li>
<li><p><strong>Make sure the authentication middleware is registered before all the other middleware, including <code>app.UseMvc()</code></strong>:</p>
<li><p><strong>Make sure the ASP.NET Core authentication middleware is correctly registered at the right place</strong>:</p>
<pre><code class="lang-csharp">public void Configure(IApplicationBuilder app)
{
app.UseAuthentication();
app.UseDeveloperExceptionPage();
app.UseMvc();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(options =&gt;
{
options.MapControllers();
options.MapDefaultControllerRoute();
});
app.UseWelcomePage();
}
</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&lt;ApplicationDbContext&gt;(options =&gt;
{
// Configure the context to use Microsoft SQL Server.
options.UseSqlServer(configuration[&quot;Data:DefaultConnection:ConnectionString&quot;]);
options.UseSqlServer(Configuration.GetConnectionString(&quot;DefaultConnection&quot;));
// Register the entity sets needed by OpenIddict.
// Note: use the generic overload if you need
@ -163,7 +173,9 @@ of OpenIddict.</p>
});
</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&lt;TKey&gt;()</code> core extension accepting a <code>TKey</code> generic argument and use the generic <code>options.UseOpenIddict&lt;TKey&gt;()</code> overload to configure Entity Framework Core to use the specified key type:</p>
<p>-&gt; [!NOTE]</p>
<blockquote><p>Important: 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&lt;TKey&gt;()</code>
core extension accepting a <code>TKey</code> generic argument and use the generic <code>options.UseOpenIddict&lt;TKey&gt;()</code> overload to configure Entity Framework Core to use the specified key type:</p>
<pre><code class="lang-csharp">services.AddOpenIddict()
.AddCore(options =&gt;
{
@ -182,67 +194,85 @@ services.AddDbContext&lt;ApplicationDbContext&gt;(options =&gt;
});
</code></pre></blockquote>
<ul>
<li><strong>Create your own authorization controller</strong>:</li>
</ul>
<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&#39;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>
<ul>
<li><p><strong>Enable the corresponding flows in the OpenIddict options</strong>:</p>
<pre><code class="lang-csharp">public void ConfigureServices(IServiceCollection services)
<li><p><strong>Create your own authorization controller:</strong>
Implementing a custom authorization controller is required to allow OpenIddict to create tokens based on the identities and claims you provide.
Here&#39;s an example for the client credentials grant:</p>
<pre><code class="lang-csharp">public class AuthorizationController : Controller
{
// Register the OpenIddict services.
services.AddOpenIddict()
.AddCore(options =&gt;
private readonly OpenIddictApplicationManager&lt;OpenIddictEntityFrameworkCoreApplication&gt; _applicationManager;
public AuthorizationController(OpenIddictApplicationManager&lt;OpenIddictEntityFrameworkCoreApplication&gt; applicationManager)
=&gt; _applicationManager = applicationManager;
[HttpPost(&quot;~/connect/token&quot;), Produces(&quot;application/json&quot;)]
public async Task&lt;IActionResult&gt; Exchange()
{
// Configure OpenIddict to use the Entity Framework Core stores and entities.
options.UseEntityFrameworkCore()
.UseDbContext&lt;ApplicationDbContext&gt;();
})
.AddServer(options =&gt;
var request = HttpContext.GetOpenIddictServerRequest();
if (request.IsClientCredentialsGrantType())
{
// Register the ASP.NET Core MVC binder used by OpenIddict.
// Note: if you don&#39;t call this method, you won&#39;t be able to
// bind OpenIdConnectRequest or OpenIdConnectResponse parameters.
options.UseMvc();
// Note: the client credentials are automatically validated by OpenIddict:
// if client_id or client_secret are invalid, this action won&#39;t be invoked.
// Enable the authorization/token endpoints (required to use the code flow).
options.EnableAuthorizationEndpoint(&quot;/connect/authorize&quot;)
.EnableTokenEndpoint(&quot;/connect/token&quot;);
var application = await _applicationManager.FindByClientIdAsync(request.ClientId);
if (application == null)
{
throw new InvalidOperationException(&quot;The application details cannot be found in the database.&quot;);
}
// Allow client applications to use the code flow.
options.AllowAuthorizationCodeFlow();
// Create a new ClaimsIdentity containing the claims that
// 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.
options.DisableHttpsRequirement();
})
// Use the client_id as the subject identifier.
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);
}
throw new NotImplementedException(&quot;The specified grant type is not implemented.&quot;);
}
}
</code></pre></li>
<li><p><strong>Register your client application</strong>:</p>
<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())
<li><p><strong>Register your client application</strong> (e.g from an <code>IHostedService</code> implementation):</p>
<pre><code class="lang-csharp">public class Worker : IHostedService
{
var provider = scope.ServiceProvider;
var context = provider.GetRequiredService&lt;ApplicationDbContext&gt;();
private readonly IServiceProvider _serviceProvider;
public Worker(IServiceProvider serviceProvider)
=&gt; _serviceProvider = serviceProvider;
public async Task StartAsync(CancellationToken cancellationToken)
{
using var scope = _serviceProvider.CreateScope();
var context = scope.ServiceProvider.GetRequiredService&lt;ApplicationDbContext&gt;();
await context.Database.EnsureCreatedAsync();
var manager = provider.GetRequiredService&lt;IOpenIddictApplicationManager&gt;();
var manager = scope.ServiceProvider.GetRequiredService&lt;OpenIddictApplicationManager&lt;OpenIddictEntityFrameworkCoreApplication&gt;&gt;();
if (await manager.FindByClientIdAsync(&quot;[client identifier]&quot;) == null)
if (await manager.FindByClientIdAsync(&quot;console&quot;) is null)
{
var descriptor = new OpenIddictApplicationDescriptor
await manager.CreateAsync(new OpenIddictApplicationDescriptor
{
ClientId = &quot;[client identifier]&quot;,
ClientSecret = &quot;[client secret]&quot;,
RedirectUris = { new Uri(&quot;[redirect uri]&quot;) }
};
await manager.CreateAsync(descriptor);
ClientId = &quot;console&quot;,
ClientSecret = &quot;388D45FA-B36B-4988-BA59-B187D329C207&quot;,
DisplayName = &quot;My client application&quot;,
Permissions =
{
Permissions.Endpoints.Token,
Permissions.GrantTypes.ClientCredentials
}
});
}
}
public Task StopAsync(CancellationToken cancellationToken) =&gt; Task.CompletedTask;
}
</code></pre></li>
</ul>

View File

@ -1,120 +0,0 @@
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Samples </title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="Samples ">
<meta name="generator" content="docfx 2.56.6.0">
<link rel="shortcut icon" href="../images/favicon.ico">
<link rel="stylesheet" href="../styles/docfx.vendor.css">
<link rel="stylesheet" href="../styles/docfx.css">
<link rel="stylesheet" href="../styles/main.css">
<link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
<meta property="docfx:navrel" content="../toc.html">
<meta property="docfx:tocrel" content="toc.html">
</head> <body data-spy="scroll" data-target="#affix" data-offset="120">
<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="../images/logo.png" 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="samples">Samples</h1>
<p><strong><a href="https://github.com/openiddict/openiddict-samples">Specialized samples can be found in the samples repository</a>:</strong></p>
<ul>
<li><a href="https://github.com/openiddict/openiddict-samples/tree/dev/samples/CodeFlow">Authorization code flow sample</a></li>
<li><a href="https://github.com/openiddict/openiddict-samples/tree/dev/samples/ImplicitFlow">Implicit flow sample</a></li>
<li><a href="https://github.com/openiddict/openiddict-samples/tree/dev/samples/PasswordFlow">Password flow sample</a></li>
<li><a href="https://github.com/openiddict/openiddict-samples/tree/dev/samples/ClientCredentialsFlow">Client credentials flow sample</a></li>
<li><a href="https://github.com/openiddict/openiddict-samples/tree/dev/samples/RefreshFlow">Refresh flow sample</a></li>
</ul>
<blockquote><p><strong>Samples for ASP.NET Core 1.x can be found <a href="https://github.com/openiddict/openiddict-samples/tree/master">in the master branch of the samples repository</a></strong>.</p>
</blockquote>
</article>
</div>
<div class="hidden-sm col-md-2" role="complementary">
<div class="sideaffix">
<div class="contribution">
<ul class="nav">
<li>
<a href="https://github.com/openiddict/openiddict-documentation/blob/dev/guide/samples.md/#L1" class="contribution-link">Improve this Doc</a>
</li>
</ul>
</div>
<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
<h5>In This Article</h5>
<div></div>
</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>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>

View File

@ -18,9 +18,6 @@
<li>
<a href="getting-started.html" name="" title="Getting started">Getting started</a>
</li>
<li>
<a href="samples.html" name="" title="Samples">Samples</a>
</li>
<li>
<a href="migration.html" name="" title="Migration guide">Migration guide</a>
</li>

View File

@ -85,7 +85,7 @@ and starting in OpenIddict 3.0, <strong>any ASP.NET 4.x or OWIN application too<
<div class="col-md-4">
<div class="panel panel-default" style="min-height: 120px;">
<div class="panel-body">
<p><strong><a href="guide/samples.html">Samples</a></strong></p>
<p><strong><a href="guide/samples.md">Samples</a></strong></p>
<p>View samples implementing the various authorization flows.</p>
</div>
</div>

View File

@ -45,7 +45,7 @@
"output": {
".html": {
"relative_path": "guide/getting-started.html",
"hash": "ff7DWdjAwYucfbMQfCyTFg=="
"hash": "B+LUpBca5+kh6NFTvwCenQ=="
}
},
"is_incremental": false,
@ -75,25 +75,13 @@
"is_incremental": false,
"version": ""
},
{
"type": "Conceptual",
"source_relative_path": "guide/samples.md",
"output": {
".html": {
"relative_path": "guide/samples.html",
"hash": "wOuQoyk0yySl5WZajiENrA=="
}
},
"is_incremental": false,
"version": ""
},
{
"type": "Toc",
"source_relative_path": "guide/toc.yml",
"output": {
".html": {
"relative_path": "guide/toc.html",
"hash": "epsbDuVdI5yEtqtUWQIS9g=="
"hash": "xm6nv4mvnxzUpj5meobWaQ=="
}
},
"is_incremental": false,
@ -122,12 +110,15 @@
"version": ""
},
{
"log_codes": [
"InvalidFileLink"
],
"type": "Conceptual",
"source_relative_path": "index.md",
"output": {
".html": {
"relative_path": "index.html",
"hash": "gInpRdPv2JGMAzcpzWUKCw=="
"hash": "mf66lbYDYJ1ueuRq2UsFNQ=="
}
},
"is_incremental": false,
@ -160,7 +151,7 @@
"ConceptualDocumentProcessor": {
"can_incremental": false,
"incrementalPhase": "build",
"total_file_count": 7,
"total_file_count": 6,
"skipped_file_count": 0
},
"ResourceDocumentProcessor": {