Merge pull request #1025 from DuendeSoftware/dh/is8-docs

Add initial IdentityServer 8.0 documentation

Author: maartenba

astro/src/content/docs/bff/extensibility/index.md

@@ -16,4 +16,4 @@ Duende.BFF can be extended in the following areas
 
 * custom logic at the session management endpoints
 * custom logic and configuration for HTTP forwarding
-* custom data storage for server-side sessions and access/refresh tokens
+* custom data storage for server-side sessions and access/refresh tokens

astro/src/content/docs/bff/fundamentals/options.md

@@ -43,16 +43,20 @@ builder.Services.AddBff(options =>
     The ASP.NET environment names that enable the diagnostics endpoint. Defaults to "Development".
 
 * ***BackChannelHttpHandler*** 
+
     A HTTP message handler that's used to configure backchannel communication. Typically used during testing. Configuring this will automatically configure the BackChannelHttpHandler property in _OpenIDConnectOptions_ and also set it as the primary http message handler for retrieving the index.html. 
 
 * ***AutomaticallyRegisterBffMiddleware*** (added in 4.0)
+
     When applying BFF V4 multiple frontends, a lot of middlewares get automatically added to the pipeline. For example, the frontend selection middleware, the authentication handlers, etc. If you don't want this automatic behavior, then you can turn it off and register these middlewares manually. 
 
 
 * ***StaticAssetsClientName***
+
     If BFF is configured to automatically retrieve the `index.html`, or to proxy the static assets, it needs an HTTP client to do so. With this name, you can automatically configure this HTTP client in the `HttpClientFactory`. 
 
 * ***AllowedSilentLoginReferers*** 
+
     For silent login to work, you normally need to have the BFF backend and the frontend on the same origin. If you have a split host scenario, meaning the backend on a different origin (but same site) as the frontend, then you can use the referer header to differentiate which browser window to post the silent login results to. This array must then contain the list of allowed referer header values. 
 
 ## Paths
@@ -162,6 +166,7 @@ builder.Services.AddBlazorServer(opt =>
 The following options are available:
 
 * ***ServerStateProviderPollingInterval*** 
+
     The delay, in milliseconds, between polling requests by the
     BffServerAuthenticationStateProvider to the /bff/user endpoint. Defaults to 5000
     ms.
@@ -180,13 +185,16 @@ builder.Services.AddBffBlazorClient(opt =>
 The following options are available:
 
 * ***RemoteApiPath*** 
+
     The base path to use for remote APIs.
 
 * ***RemoteApiBaseAddress*** 
+
     The base address to use for remote APIs. If unset (the default), the
     blazor hosting environment's base address is used.
 
 * ***StateProviderBaseAddress*** 
+
     The base address to use for the state provider's calls to the /bff/user
     endpoint. If unset (the default), the blazor hosting environment's base
     address is used.
@@ -197,6 +205,7 @@ The following options are available:
     start polling the /bff/user endpoint. Defaults to 1000 ms.
 
 * ***WebAssemblyStateProviderPollingInterval*** 
+
     The delay, in milliseconds, between polling requests by the
     BffClientAuthenticationStateProvider to the /bff/user endpoint. Defaults to 5000
     ms.

astro/src/content/docs/identityserver/aspnet-identity/schemes.md

@@ -16,6 +16,8 @@ When a user logs in, their identity is established and persisted across requests
 
 When using IdentityServer without ASP.NET Identity, the default cookie scheme is named `"idsrv"`, though we recommend using the constant `IdentityServerConstants.DefaultCookieAuthenticationScheme` in your code if you ever need it.
 
+Starting in **v8.0**, the default cookie name (not the scheme name) has changed to `"__Host-idsrv"` to improve security. The scheme name remains `"idsrv"`. See [Cookie Name Migration (v8.0)](#cookie-name-migration-v80) below for upgrade instructions.
+
 The default cookie scheme is configured by default in `AddIdentityServer()`, which sets up the cookie authentication handler with this scheme name. This cookie is essential for:
 
 - maintaining the user's authenticated session
@@ -39,7 +41,7 @@ services.ConfigureApplicationCookie(options =>
 {
     // The default ("Identity.Application")
     options.Cookie.Name = IdentityConstants.ApplicationScheme;
-    
+
     // Configure other options here...
     options.ExpireTimeSpan = TimeSpan.FromHours(1);
     options.SlidingExpiration = true;
@@ -57,6 +59,8 @@ This allows your login logic to read the claims from the external provider befor
 
 IdentityServer always uses the `"idsrv.external"` scheme here, available in the `IdentityServerConstants.ExternalCookieAuthenticationScheme` constant.
 
+Starting in **v8.0**, the default cookie _name_ for this scheme has changed to `"__Host-idsrv.external"` (previously `"idsrv.external"`). See [Cookie Name Migration (v8.0)](#cookie-name-migration-v80) below for upgrade instructions.
+
 ### Check Session Cookie
 
 IdentityServer session management requires a separate cookie to monitor the session state without sending the large authentication cookie.
@@ -66,6 +70,24 @@ The [User Session Service](/identityserver/reference/services/user-session-servi
 
 Note this cookie is not marked as `HttpOnly`, so it can be accessed in client-side code. The JavaScript code that is required to check user sessions in the background also requires access to this cookie, and needs it to be `HttpOnly`.
 
+## Cookie Name Migration :badge[v8.0]
+
+In IdentityServer v8.0, the default cookie **names** changed to use the `__Host-` prefix for
+improved security. The `__Host-` prefix restricts cookies to HTTPS-only, `Path=/`, and no `Domain`
+attribute — providing defense-in-depth against cookie theft and session fixation attacks.
+
+| Cookie               | Old name (v7.x)  | New name (v8.0)         |
+| -------------------- | ---------------- | ----------------------- |
+| Primary auth cookie  | `idsrv`          | `__Host-idsrv`          |
+| External auth cookie | `idsrv.external` | `__Host-idsrv.external` |
+
+The authentication **scheme names** (`"idsrv"` and `"idsrv.external"`) are unchanged.
+
+A migration middleware is available to transparently re-issue old cookies under the new names,
+and the cookie names can be overridden via `AuthenticationOptions`. See the
+[upgrade guide](/identityserver/upgrades/v7_4-to-v8_0.md#cookie-names-changed-to-__host--prefix)
+for full migration instructions.
+
 ## Common Pitfalls
 
 - **Mixing Schemes:** Attempting to `SignOutAsync("idsrv")` when ASP.NET Identity is in use will have no effect on the actual `"Identity.Application"` cookie, leaving the user logged in. Always use the constants or the helper services (like `SignInManager`) that match your configuration.

astro/src/content/docs/identityserver/diagnostics/conformance-report.md

@@ -0,0 +1,163 @@
+---
+title: "Conformance Report"
+description: How to install, configure, and use the IdentityServer conformance report to assess OAuth 2.1 and FAPI 2.0 compliance.
+date: 2026-03-02
+sidebar:
+  label: Conformance Report
+  order: 60
+  badge:
+    text: v8.0
+    variant: tip
+---
+
+<span data-shb-badge data-shb-badge-variant="default">Added in 8.0 (prerelease)</span>
+
+The conformance report assesses your IdentityServer deployment against
+[OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1) and
+[FAPI 2.0 Security Profile](https://openid.net/specs/fapi-2_0-security-profile.html) specifications,
+generating an HTML report accessible via a protected endpoint.
+
+## Installation
+
+Install the NuGet package:
+
+```bash title="Terminal"
+dotnet add package Duende.IdentityServer.ConformanceReport --prerelease
+```
+
+## Setup
+
+### 1. Register the Conformance Report
+
+Call `AddConformanceReport()` on the IdentityServer builder:
+
+```csharp
+// Program.cs
+builder.Services.AddIdentityServer()
+    .AddConformanceReport(options =>
+    {
+        options.Enabled = true;
+    });
+```
+
+### 2. Map the Endpoint
+
+Add the conformance report endpoint to your middleware pipeline:
+
+```csharp
+// Program.cs
+app.MapConformanceReport();
+```
+
+### 3. Access the Report
+
+Navigate to: `https://your-server/_duende/conformance-report`
+
+The endpoint requires an authenticated user by default (see [Authorization](#authorization) below).
+
+## Configuration Options
+
+`ConformanceReportOptions` controls the conformance report feature:
+
+* **`Enabled`**
+  Enable or disable the conformance report endpoint. Defaults to `false`.
+
+* **`EnableOAuth21Assessment`**
+  Include OAuth 2.1 profile assessment in the report. Defaults to `true`.
+
+* **`EnableFapi2SecurityAssessment`**
+  Include FAPI 2.0 Security Profile assessment in the report. Defaults to `true`.
+
+* **`PathPrefix`**
+  URL path prefix for the conformance endpoint (no leading slash). Defaults to `"_duende"`.
+
+* **`ConfigureAuthorization`**
+  Authorization policy for the HTML report endpoint. Defaults to require an authenticated user.
+
+* **`AuthorizationPolicyName`**
+  ASP.NET Core authorization policy name used internally. Defaults to `"ConformanceReport"`.
+
+* **`HostCompanyName`**
+  Optional company name shown in the report header. Defaults to `null`.
+
+* **`HostCompanyLogoUrl`**
+  Optional company logo URL shown in the report header. Defaults to `null`.
+
+## Authorization
+
+By default, the report endpoint requires an authenticated user. Customize the policy using
+`ConfigureAuthorization`:
+
+```csharp
+// Program.cs
+builder.Services.AddIdentityServer()
+    .AddConformanceReport(options =>
+    {
+        options.Enabled = true;
+
+        // Require a specific role
+        options.ConfigureAuthorization = policy => policy.RequireRole("Admin");
+
+        // Or require multiple conditions
+        // options.ConfigureAuthorization = policy => policy
+        //     .RequireRole("Admin")
+        //     .RequireClaim("department", "IT");
+
+        // Or allow anonymous (development/testing only)
+        // options.ConfigureAuthorization = policy =>
+        //     policy.RequireAssertion(_ => builder.Environment.IsDevelopment());
+    });
+```
+
+:::caution
+If you set `ConfigureAuthorization = null`, you must manually register an ASP.NET Core authorization
+policy with the name specified in `AuthorizationPolicyName` (default: `"ConformanceReport"`).
+Otherwise, the endpoint will fail at runtime with a "policy not found" error.
+:::
+
+## Understanding the Report
+
+The HTML report displays:
+
+* **Server Configuration** — a matrix of server-level conformance rules and their status
+* **Client Configurations** — a matrix of per-client conformance rules and their status
+* **Rule Legend** — explanation of each rule identifier
+* **Notes** — detailed messages for warnings and failures
+
+### Status Indicators
+
+| Symbol  | Meaning                                                  |
+| ------- | -------------------------------------------------------- |
+| Pass    | Requirement is met                                       |
+| Fail    | Requirement is not met (configuration is non-conformant) |
+| Warning | Recommended practice is not followed                     |
+| N/A     | Rule is not applicable to this configuration             |
+
+## Requirements
+
+The conformance report uses `IClientStore.GetAllClientsAsync` to enumerate all clients for
+assessment. Custom `IClientStore` implementations must implement this method (added in v8.0).
+See the [upgrade guide](/identityserver/upgrades/v7_4-to-v8_0/#iclientstoregettallclientsasync-now-required)
+for details.
+
+## Full Example
+
+```csharp
+// Program.cs
+
+builder.Services.AddIdentityServer()
+    .AddInMemoryClients(Config.Clients)
+    .AddConformanceReport(options =>
+    {
+        options.Enabled = true;
+        options.EnableOAuth21Assessment = true;
+        options.EnableFapi2SecurityAssessment = true;
+        options.HostCompanyName = "Acme Corp";
+        options.ConfigureAuthorization = policy => policy.RequireRole("ComplianceTeam");
+    });
+
+// ...
+
+app.MapConformanceReport();
+app.UseIdentityServer();
+```

astro/src/content/docs/identityserver/diagnostics/index.md

@@ -33,4 +33,11 @@ systems (APM). They used to have their own different APIs so IdentityServer only
 that could be used to call the APM's APIs. Thanks to OpenTelemetry there is now a standardized
 way to emit diagnostic information from a process. The events may eventually be deprecated and removed.
 
-[Read More](/identityserver/diagnostics/events.md)
+[Read More](/identityserver/diagnostics/events.md)
+
+## Conformance Report
+
+IdentityServer can generate a conformance report that assesses your configuration against OAuth 2.1
+and FAPI 2.0 specifications.
+
+[Read More](/identityserver/diagnostics/conformance-report/)