Merge pull request #368 from DuendeSoftware/anders/v7-updates

Add v7 docs

.gitignore

@@ -4,6 +4,7 @@
 # hugo
 public
 root/identityserver/
+.hugo_build.lock
 
 # .net
 [Dd]ebug/

IdentityServer/v5/docs/content/_index.md

@@ -6,6 +6,10 @@ weight: 1
 # Duende IdentityServer v5 Documentation
 The most flexible & standards-compliant OpenID Connect and OAuth 2.0 framework for ASP.NET Core.
 
+{{% notice warning %}}
+Version 5.x out of support since December 13, 2022. We strongly recommend upgrading to a supported version.
+{{% /notice %}}
+
 {{% notice note %}}
-This is the documentation for version 5.x. You can find the v6.x documentation [here](https://docs.duendesoftware.com/identityserver/v6).
+This is the documentation for version 5.x. You can find the v6.x documentation [here](https://docs.duendesoftware.com/identityserver/v6) and the v7.x documentation [here](https://docs.duendesoftware.com/identityserver/v7).
 {{% /notice %}}

IdentityServer/v5/docs/content/apis/_index.md

@@ -11,5 +11,5 @@ Duende IdentityServer issues tokens for accessing resources.
 
 These resources are very often HTTP-based APIs, but could be also other "invokable" functionality like messaging endpoints, gRPC services or even good old XML Web Services. See the [issuing tokens]({{< ref "/tokens" >}}) section on more information on access tokens and how to request them.
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}
 

IdentityServer/v5/docs/content/apis/aspnetcore/_index.md

@@ -7,5 +7,5 @@ chapter = true
 
 # Protecting APIs using ASP.NET Core
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}
 

IdentityServer/v5/docs/content/deployment/_index.md

@@ -9,4 +9,4 @@ chapter = true
 
 Duende IdentityServer is just middleware that you host in ASP.NET Core. All [rules and advice](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/) around deploying ASP.NET Core applications to various hosting environments apply here too. This section focuses on IdentityServer-specific concerns.
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/diagnostics/_index.md

@@ -7,4 +7,4 @@ chapter = true
 
 # Diagnostics
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/fundamentals/_index.md

@@ -6,4 +6,4 @@ chapter = true
 
 # Fundamentals
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/fundamentals/resources/_index.md

@@ -9,4 +9,4 @@ chapter = true
 
 The ultimate job of Duende IdentityServer is to control access to resources.
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/overview/_index.md

@@ -8,4 +8,4 @@ chapter = true
 # Overview
 
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/quickstarts/_index.md

@@ -9,4 +9,4 @@ chapter = true
 
 The following hands-on tutorials guide you through a couple of common scenarios.
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/reference/_index.md

@@ -7,4 +7,4 @@ chapter = true
 
 # Reference
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/reference/endpoints/_index.md

@@ -6,4 +6,4 @@ chapter = true
 
 # Endpoints
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/reference/models/_index.md

@@ -6,4 +6,4 @@ chapter = true
 
 # Models
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/reference/response_handling/_index.md

@@ -6,4 +6,4 @@ chapter = true
 
 # Response Generators
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/reference/services/_index.md

@@ -6,4 +6,4 @@ chapter = true
 
 # Services
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/reference/stores/_index.md

@@ -6,4 +6,4 @@ chapter = true
 
 # Stores
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/reference/validators/_index.md

@@ -6,4 +6,4 @@ chapter = true
 
 # Validators
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/tokens/_index.md

@@ -9,4 +9,4 @@ chapter = true
 
 At its very heart, Duende IdentityServer is a so-called *Security Token Service* (STS).
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v5/docs/content/tokens/authentication/_index.md

@@ -7,5 +7,5 @@ chapter = true
 
 # Client Authentication
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}
 

IdentityServer/v5/docs/content/upgrades/_index.md

@@ -8,4 +8,4 @@ chapter = true
 
 Here is a list of upgrade guides.
 
-{{%children style="h4" %}}
+{{%children style="h4" /%}}

IdentityServer/v6/docs/content/_index.md

@@ -7,5 +7,13 @@ weight: 1
 The most flexible & standards-compliant OpenID Connect and OAuth 2.0 framework for ASP.NET Core.
 
 {{% notice note %}}
-This is the documentation for version 6.x. You can find the v5.x documentation [here](https://docs.duendesoftware.com/identityserver/v5).
+This is the documentation for version 6.x. You can find the v5.x documentation [here](https://docs.duendesoftware.com/identityserver/v5) and the v7.x documentation [here](https://docs.duendesoftware.com/identityserver/v7).
 {{% /notice %}}
+
+{{% notice note %}}
+Version 6.x is supported on .NET 6 and .NET 7. Version 6.x is supported until November 12, 2024 when .NET 6 support ends.
+{{% /notice %}}
+
+{{% notice info %}}
+Version 6.x is supported not supported on .NET 8. Please use [v7.x](https://docs.duendesoftware.com/identityserver/v7) for .NET 8.
+{{% /notice %}}

IdentityServer/v7/docs/archetypes/default.md

@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
+

IdentityServer/v7/docs/cheatsheet.md

@@ -0,0 +1,15 @@
+[See part 2]({{< ref "/quickstarts/2_interactive" >}})
+
+[See part 2]({{< ref "2_interactive.md" >}})
+
+{{< ref "2_interactive.md" >}}
+
+[See part 1 - defining an API scope]({{< ref "1_client_credentials#defining-an-api-scope" >}})
+
+{{< param qs_base >}}
+
+{{% notice note %}}
+...
+{{% /notice %}}
+
+![](../images/1_client_screenshot.png)

IdentityServer/v7/docs/config.toml

@@ -0,0 +1,13 @@
+baseURL = "https://docs.duendesoftware.com/identityserver/v7"
+languageCode = "en-us"
+title = "Duende IdentityServer Documentation"
+
+theme = "hugo-theme-learn"
+# For search functionality
+[outputs]
+home = [ "HTML", "RSS", "JSON"]
+
+[params]
+editURL = "https://github.com/DuendeSoftware/docs.duendesoftware.com/edit/main/IdentityServer/v7/docs/content/"
+qs_base = "https://github.com/DuendeSoftware/Samples/tree/main/IdentityServer/v7/Quickstarts"
+samples_base = "https://github.com/DuendeSoftware/Samples/tree/main/IdentityServer/v7"

IdentityServer/v7/docs/content/_index.md

@@ -0,0 +1,15 @@
+---
+title: "Home"
+weight: 1
+---
+
+# Duende IdentityServer v7 Documentation
+The most flexible & standards-compliant OpenID Connect and OAuth 2.0 framework for ASP.NET Core.
+
+{{% notice info %}}
+Version 7.x is available as preview and not supported for production use. The RTM release is planned for January 2024.
+{{% /notice %}}
+
+{{% notice note %}}
+This is the documentation for version 7.x. You can find the v6.x documentation [here](https://docs.duendesoftware.com/identityserver/v6).
+{{% /notice %}}

IdentityServer/v7/docs/content/apis/_index.md

@@ -0,0 +1,15 @@
++++
+title = "Protecting APIs"
+date = 2020-09-10T08:20:20+02:00
+weight = 60
+chapter = true
++++
+
+# Protecting APIs
+
+Duende IdentityServer issues tokens for accessing resources.
+
+These resources are very often HTTP-based APIs, but could be also other "invocable" functionality like messaging endpoints, gRPC services or even good old XML Web Services. See the [issuing tokens]({{< ref "/tokens" >}}) section on more information on access tokens and how to request them.
+
+{{%children style="h4" /%}}
+

IdentityServer/v7/docs/content/apis/add_apis.md

@@ -0,0 +1,111 @@
+---
+title: "Adding API Endpoints to your IdentityServer"
+date: 2020-09-10T08:22:12+02:00
+weight: 20
+---
+
+It's a common scenario to add additional API endpoints to the application hosting IdentityServer.
+These endpoints are typically protected by IdentityServer itself.
+
+For simple scenarios, we give you some helpers. See the advanced section to understand more of the internal plumbing.
+
+{{% notice note %}}
+You could achieve the same by using either Microsoft's *JwtBearer* handler. But this requires more configuration and creates dependencies on external libraries that might lead to conflicts in future updates.
+{{% /notice %}}
+
+Start by registering your API as an *ApiScope*, (or resource) e.g.:
+
+```cs
+var scopes = new List<ApiScope>
+{
+    // local API
+    new ApiScope(IdentityServerConstants.LocalApi.ScopeName),
+};
+```
+
+..and give your clients access to this API, e.g.:
+
+```cs
+new Client
+{
+    // rest omitted
+    AllowedScopes = { IdentityServerConstants.LocalApi.ScopeName },   
+}
+```
+
+{{% notice note %}}
+The value of *IdentityServerConstants.LocalApi.ScopeName* is *IdentityServerApi*.
+{{% /notice %}}
+
+To enable token validation for local APIs, add the following to your IdentityServer startup:
+
+```cs
+services.AddLocalApiAuthentication();
+```
+
+To protect an API controller, decorate it with an *Authorize* attribute using the *LocalApi.PolicyName* policy:
+
+```cs
+[Route("localApi")]
+[Authorize(LocalApi.PolicyName)]
+public class LocalApiController : ControllerBase
+{
+    public IActionResult Get()
+    {
+        // omitted
+    }
+}
+```
+
+Authorized clients can then request a token for the *IdentityServerApi* scope and use it to call the API.
+
+## Discovery
+You can also add your endpoints to the discovery document if you want, e.g like this::
+
+```cs
+services.AddIdentityServer(options =>
+{
+    options.Discovery.CustomEntries.Add("local_api", "~/localapi");
+})
+```
+
+## Advanced
+Under the covers, the *AddLocalApiAuthentication* helper does a couple of things:
+
+* adds an authentication handler that validates incoming tokens using IdentityServer's built-in token validation engine (the name of this handler is *IdentityServerAccessToken* or *IdentityServerConstants.LocalApi.AuthenticationScheme*
+* configures the authentication handler to require a scope claim inside the access token of value *IdentityServerApi*
+* sets up an authorization policy that checks for a scope claim of value *IdentityServerApi*
+
+This covers the most common scenarios. You can customize this behavior in the following ways:
+
+* Add the authentication handler yourself by calling *services.AddAuthentication().AddLocalApi(...)*
+    * this way you can specify the required scope name yourself, or (by specifying no scope at all) accept any token from the current IdentityServer instance
+* Do your own scope validation/authorization in your controllers using custom policies or code, e.g.:
+
+
+```cs
+    services.AddAuthorization(options =>
+    {
+        options.AddPolicy(IdentityServerConstants.LocalApi.PolicyName, policy =>
+        {
+            policy.AddAuthenticationSchemes(IdentityServerConstants.LocalApi.AuthenticationScheme);
+            policy.RequireAuthenticatedUser();
+            // custom requirements
+        });
+    });
+```
+
+## Claims Transformation
+You can provide a callback to transform the claims of the incoming token after validation.
+Either use the helper method, e.g.:
+
+```cs
+services.AddLocalApiAuthentication(principal =>
+{
+    principal.Identities.First().AddClaim(new Claim("additional_claim", "additional_value"));
+
+    return Task.FromResult(principal);
+});
+```
+
+...or implement the event on the options if you add the authentication handler manually.

IdentityServer/v7/docs/content/apis/aspnetcore/_index.md

@@ -0,0 +1,11 @@
++++
+title = "Protecting APIs using ASP.NET Core"
+date = 2020-09-10T08:20:20+02:00
+weight = 10
+chapter = true
++++
+
+# Protecting APIs using ASP.NET Core
+
+{{%children style="h4" /%}}
+