Add intro, getting started and samples sections

guide/getting-started.md

@@ -0,0 +1,176 @@
+# Getting started
+
+To use OpenIddict, 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**.
+
+  - **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.
+
+  - **Add the appropriate MyGet repositories to your NuGet sources**. This can be done by adding a new `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="aspnet-contrib" value="https://www.myget.org/F/aspnet-contrib/api/v3/index.json" />
+    </packageSources>
+    </configuration>
+    ```
+
+  - **Update your `.csproj` file** to reference `AspNet.Security.OAuth.Validation` and the `OpenIddict` packages:
+
+    ```xml
+    <PackageReference Include="AspNet.Security.OAuth.Validation" Version="2.0.0-*" />
+    <PackageReference Include="OpenIddict" Version="2.0.0-*" />
+    <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-*" />
+    <PackageReference Include="OpenIddict.Mvc" Version="2.0.0-*" />
+    ```
+
+  - **Configure the OpenIddict 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 OAuth2 validation handler.
+        services.AddAuthentication()
+            .AddOAuthValidation();
+
+        // Register the OpenIddict services.
+        // Note: use the generic overload if you need
+        // to replace the default OpenIddict entities.
+        services.AddOpenIddict(options =>
+        {
+            // Register the Entity Framework stores.
+            options.AddEntityFrameworkCoreStores<ApplicationDbContext>();
+
+            // 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.AddMvcBinders();
+
+            // Enable the token endpoint (required to use the password flow).
+            options.EnableTokenEndpoint("/connect/token");
+
+            // Allow client applications to use the grant_type=password flow.
+            options.AllowPasswordFlow();
+
+            // During development, you can disable the HTTPS requirement.
+            options.DisableHttpsRequirement();
+        });
+    }
+    ```
+
+    > **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.
+
+  - **Make sure the authentication middleware is registered before all the other middleware, including `app.UseMvc()`**:
+
+    ```csharp
+    public void Configure(IApplicationBuilder app)
+    {
+        app.UseAuthentication();
+
+        app.UseMvc();
+    }
+    ```
+
+  - **Update your Entity Framework Core context registration to register the OpenIddict entities**:
+
+    ```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();
+    });
+    ```
+
+    > **Note:** if you change the default entity primary key (e.g. to `int` or `Guid` instead of `string`), make sure to use the `services.AddOpenIddict()` extension accepting a `TKey` generic argument and use the generic `options.UseOpenIddict<TKey>()` overload.
+
+  - **Create your own authorization controller**:
+
+    To **support the password or the client credentials flow, you must provide your own token endpoint action**.
+    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
+    public void ConfigureServices(IServiceCollection services)
+    {
+        // Register the OpenIddict services.
+        // Note: use the generic overload if you need
+        // to replace the default OpenIddict entities.
+        services.AddOpenIddict(options =>
+        {
+            // Register the Entity Framework stores.
+            options.AddEntityFrameworkCoreStores<ApplicationDbContext>();
+
+            // 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.AddMvcBinders();
+
+            // 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();
+        });
+    }
+    ```
+
+  - **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);
+        }
+    }
+    ```

guide/index.md

@@ -0,0 +1,22 @@
+# Introduction
+
+## 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 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.
+
+Note: OpenIddict natively supports **[Entity Framework Core](https://github.com/aspnet/EntityFramework)** and **[Entity Framework 6](https://github.com/aspnet/EntityFramework6)** 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.
+
+## Why an OpenID Connect server?
+
+Adding an OpenID Connect server to your application **allows you to support token authentication**.
+It also allows you to manage all your users using local password or an external identity provider
+(e.g. Facebook or Google) for all your applications in one central place,
+with the power to control who can access your API and the information that is exposed to each client.

guide/samples.md

@@ -0,0 +1,11 @@
+# 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)**.

guide/toc.yml

@@ -0,0 +1,6 @@
+- name: Introduction
+  href: index.md
+- name: Getting started
+  href: getting-started.md
+- name: Samples
+  href: samples.md

index.md

@@ -1,2 +1,30 @@
-# This is the **OpenIddict documentation**.
-Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files.
+# OpenIddict: the OpenID Connect server you'll be addicted to
+
+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**.
+
+<div class="row">
+    <div class="col-md-4">
+        <div class="panel panel-default" style="min-height: 120px;">
+            <div class="panel-body">
+                <p><strong><a href="guide/index.md">Introduction</a></strong></p>
+                <p>Read an introduction on OpenIddict and the reason it was created.</p>
+            </div>
+        </div>
+    </div>
+    <div class="col-md-4">
+        <div class="panel panel-default" style="min-height: 120px;">
+            <div class="panel-body">
+                <p><strong><a href="guide/getting-started.md">Getting started</a></strong></p>
+                Get started quickly by working through this step-by-step guide.
+            </div>
+        </div>
+    </div>
+    <div class="col-md-4">
+        <div class="panel panel-default" style="min-height: 120px;">
+            <div class="panel-body">
+                <p><strong><a href="guide/samples.md">Samples</a></strong></p>
+                <p>View samples implementing the various authorization flows.</p>
+            </div>
+        </div>
+    </div>
+</div>

introduction/index.md

@@ -1 +0,0 @@
-# Add your introductions here!

introduction/toc.yml

@@ -1,2 +0,0 @@
-- name: Introduction
-  href: index.md

toc.yml

@@ -1,2 +1,2 @@
-- name: Introduction
-  href: introduction/index.md
+- name: User guide
+  href: guide/index.md