Update the documentation pages

guide/getting-started.html

@@ -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;
+<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;2.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
+<li><p><strong>Configure the OpenIddict core, server and validation services</strong> in <code>Startup.ConfigureServices</code>.
-of OpenIddict.</p>
+Here&#39;s an example for the client credentials grant, used in machine-to-machine scenarios:</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>
 <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.
+            // Enable the token endpoint.
-            // Note: if you don&#39;t call this method, you won&#39;t be able to
+            options.SetTokenEndpointUris(&quot;/connect/token&quot;);
-            // bind OpenIdConnectRequest or OpenIdConnectResponse parameters.
-            options.UseMvc();
 
-            // Enable the token endpoint (required to use the password flow).
+            // Enable the client credentials flow.
-            options.EnableTokenEndpoint(&quot;/connect/token&quot;);
+            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-specific options.
-            options.DisableHttpsRequirement();
+            options.UseAspNetCore()
-
+                  .EnableTokenEndpointPassthrough();
-            // Accept token requests that don&#39;t specify a client_id.
-            options.AcceptAnonymousClients();
         })
 
-        .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>
+<li><p><strong>Create your own authorization controller:</strong>
-</ul>
+Implementing a custom authorization controller is required to allow OpenIddict to create tokens based on the identities and claims you provide.
-<p>To <strong>support the password or the client credentials flow, you must provide your own token endpoint action</strong>.
+Here&#39;s an example for the client credentials grant:</p>
-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>
+<pre><code class="lang-csharp">public class AuthorizationController : Controller
-<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)
 {
-    // Register the OpenIddict services.
+    private readonly OpenIddictApplicationManager&lt;OpenIddictEntityFrameworkCoreApplication&gt; _applicationManager;
-    services.AddOpenIddict()
+
-        .AddCore(options =&gt;
+    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.
+        var request = HttpContext.GetOpenIddictServerRequest();
-            options.UseEntityFrameworkCore()
+        if (request.IsClientCredentialsGrantType())
-                   .UseDbContext&lt;ApplicationDbContext&gt;();
-        })
-
-        .AddServer(options =&gt;
         {
-            // Register the ASP.NET Core MVC binder used by OpenIddict.
+            // Note: the client credentials are automatically validated by OpenIddict:
-            // Note: if you don&#39;t call this method, you won&#39;t be able to
+            // if client_id or client_secret are invalid, this action won&#39;t be invoked.
-            // bind OpenIdConnectRequest or OpenIdConnectResponse parameters.
-            options.UseMvc();
 
-            // Enable the authorization/token endpoints (required to use the code flow).
+            var application = await _applicationManager.FindByClientIdAsync(request.ClientId);
-            options.EnableAuthorizationEndpoint(&quot;/connect/authorize&quot;)
+            if (application == null)
-                   .EnableTokenEndpoint(&quot;/connect/token&quot;);
+            {
+                throw new InvalidOperationException(&quot;The application details cannot be found in the database.&quot;);
+            }
 
-            // 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);
+        }
+
+        throw new NotImplementedException(&quot;The specified grant type is not implemented.&quot;);
+    }
 }
 </code></pre></li>
-<li><p><strong>Register your client application</strong>:</p>
+<li><p><strong>Register your client application</strong> (e.g from an <code>IHostedService</code> implementation):</p>
-<pre><code class="lang-csharp">// Create a new service scope to ensure the database context
+<pre><code class="lang-csharp">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&lt;ApplicationDbContext&gt;();
+
+    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;,
+                ClientId = &quot;console&quot;,
-            ClientSecret = &quot;[client secret]&quot;,
+                ClientSecret = &quot;388D45FA-B36B-4988-BA59-B187D329C207&quot;,
-            RedirectUris = { new Uri(&quot;[redirect uri]&quot;) }
+                DisplayName = &quot;My client application&quot;,
-        };
+                Permissions =
-
+                {
-        await manager.CreateAsync(descriptor);
+                    Permissions.Endpoints.Token,
+                    Permissions.GrantTypes.ClientCredentials
                 }
+            });
+        }
+    }
+
+    public Task StopAsync(CancellationToken cancellationToken) =&gt; Task.CompletedTask;
 }
 </code></pre></li>
 </ul>

guide/samples.html

@@ -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>

guide/toc.html

@@ -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>

index.html

@@ -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>

manifest.json

@@ -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": {