Skip to content

Commit d34abe6

Browse files
damianhmaartenba
damianh
authored and
maartenba
committed
Add IdentityServer 8.0 documentation
- Upgrade guide (v7.4 to v8.0) with breaking changes, migration steps, and SQL Server DDL - SAML 2.0 Identity Provider section (5 pages: overview, configuration, endpoints, extensibility, service providers) - Conformance report page (installation, configuration, authorization, usage) - SAML service provider store reference - Style guide compliance fixes across all new and modified files - Delete duplicate user-endpoint-claims.md (content exists in user.mdx)
1 parent 2fa1ec8 commit d34abe6

28 files changed

Lines changed: 1913 additions & 534 deletions

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,4 @@ Duende.BFF can be extended in the following areas
1616

1717
* custom logic at the session management endpoints
1818
* custom logic and configuration for HTTP forwarding
19-
* custom data storage for server-side sessions and access/refresh tokens
19+
* custom data storage for server-side sessions and access/refresh tokens

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

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ When a user logs in, their identity is established and persisted across requests
1616

1717
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.
1818

19+
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.
20+
1921
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:
2022

2123
- maintaining the user's authenticated session
@@ -39,7 +41,7 @@ services.ConfigureApplicationCookie(options =>
3941
{
4042
// The default ("Identity.Application")
4143
options.Cookie.Name = IdentityConstants.ApplicationScheme;
42-
44+
4345
// Configure other options here...
4446
options.ExpireTimeSpan = TimeSpan.FromHours(1);
4547
options.SlidingExpiration = true;
@@ -57,6 +59,8 @@ This allows your login logic to read the claims from the external provider befor
5759

5860
IdentityServer always uses the `"idsrv.external"` scheme here, available in the `IdentityServerConstants.ExternalCookieAuthenticationScheme` constant.
5961

62+
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.
63+
6064
### Check Session Cookie
6165

6266
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
6670

6771
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`.
6872

73+
## Cookie Name Migration :badge[v8.0]
74+
75+
In IdentityServer v8.0, the default cookie **names** changed to use the `__Host-` prefix for
76+
improved security. The `__Host-` prefix restricts cookies to HTTPS-only, `Path=/`, and no `Domain`
77+
attribute — providing defense-in-depth against cookie theft and session fixation attacks.
78+
79+
| Cookie | Old name (v7.x) | New name (v8.0) |
80+
| -------------------- | ---------------- | ----------------------- |
81+
| Primary auth cookie | `idsrv` | `__Host-idsrv` |
82+
| External auth cookie | `idsrv.external` | `__Host-idsrv.external` |
83+
84+
The authentication **scheme names** (`"idsrv"` and `"idsrv.external"`) are unchanged.
85+
86+
A migration middleware is available to transparently re-issue old cookies under the new names,
87+
and the cookie names can be overridden via `AuthenticationOptions`. See the
88+
[upgrade guide](/identityserver/upgrades/v7_4-to-v8_0.md#cookie-names-changed-to-__host--prefix)
89+
for full migration instructions.
90+
6991
## Common Pitfalls
7092

7193
- **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‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: "Conformance Report"
3+
description: How to install, configure, and use the IdentityServer conformance report to assess OAuth 2.1 and FAPI 2.0 compliance.
4+
date: 2026-03-02
5+
sidebar:
6+
label: Conformance Report
7+
order: 50
8+
badge:
9+
text: v8.0
10+
variant: tip
11+
---
12+
13+
The conformance report assesses your IdentityServer deployment against
14+
[OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1) and
15+
[FAPI 2.0 Security Profile](https://openid.net/specs/fapi-2_0-security-profile.html) specifications,
16+
generating an HTML report accessible via a protected endpoint.
17+
18+
## Installation
19+
20+
Install the NuGet package:
21+
22+
```bash title="Terminal"
23+
dotnet add package Duende.IdentityServer.ConformanceReport
24+
```
25+
26+
## Setup
27+
28+
### 1. Register the Conformance Report
29+
30+
Call `AddConformanceReport()` on the IdentityServer builder:
31+
32+
```csharp
33+
// Program.cs
34+
builder.Services.AddIdentityServer()
35+
.AddConformanceReport(options =>
36+
{
37+
options.Enabled = true;
38+
});
39+
```
40+
41+
### 2. Map the Endpoint
42+
43+
Add the conformance report endpoint to your middleware pipeline:
44+
45+
```csharp
46+
// Program.cs
47+
app.MapConformanceReport();
48+
```
49+
50+
### 3. Access the Report
51+
52+
Navigate to: `https://your-server/_duende/conformance-report`
53+
54+
The endpoint requires an authenticated user by default (see [Authorization](#authorization) below).
55+
56+
## Configuration Options
57+
58+
`ConformanceReportOptions` controls the conformance report feature:
59+
60+
| Property | Type | Default | Description |
61+
| ------------------------------- | ------------------------------------- | --------------------------- | ---------------------------------------------------------------- |
62+
| `Enabled` | `bool` | `false` | Enable or disable the conformance report endpoint. |
63+
| `EnableOAuth21Assessment` | `bool` | `true` | Include OAuth 2.1 profile assessment in the report. |
64+
| `EnableFapi2SecurityAssessment` | `bool` | `true` | Include FAPI 2.0 Security Profile assessment in the report. |
65+
| `PathPrefix` | `string` | `"_duende"` | URL path prefix for the conformance endpoint (no leading slash). |
66+
| `ConfigureAuthorization` | `Action<AuthorizationPolicyBuilder>?` | Requires authenticated user | Authorization policy for the HTML report endpoint. |
67+
| `AuthorizationPolicyName` | `string` | `"ConformanceReport"` | ASP.NET Core authorization policy name used internally. |
68+
| `HostCompanyName` | `string?` | `null` | Optional company name shown in the report header. |
69+
| `HostCompanyLogoUrl` | `Uri?` | `null` | Optional company logo URL shown in the report header. |
70+
71+
## Authorization
72+
73+
By default, the report endpoint requires an authenticated user. Customize the policy using
74+
`ConfigureAuthorization`:
75+
76+
```csharp
77+
// Program.cs
78+
builder.Services.AddIdentityServer()
79+
.AddConformanceReport(options =>
80+
{
81+
options.Enabled = true;
82+
83+
// Require a specific role
84+
options.ConfigureAuthorization = policy => policy.RequireRole("Admin");
85+
86+
// Or require multiple conditions
87+
// options.ConfigureAuthorization = policy => policy
88+
// .RequireRole("Admin")
89+
// .RequireClaim("department", "IT");
90+
91+
// Or allow anonymous (development/testing only)
92+
// options.ConfigureAuthorization = policy =>
93+
// policy.RequireAssertion(_ => builder.Environment.IsDevelopment());
94+
});
95+
```
96+
97+
:::caution
98+
If you set `ConfigureAuthorization = null`, you must manually register an ASP.NET Core authorization
99+
policy with the name specified in `AuthorizationPolicyName` (default: `"ConformanceReport"`).
100+
Otherwise, the endpoint will fail at runtime with a "policy not found" error.
101+
:::
102+
103+
## Understanding the Report
104+
105+
The HTML report displays:
106+
107+
* **Server Configuration** — a matrix of server-level conformance rules and their status
108+
* **Client Configurations** — a matrix of per-client conformance rules and their status
109+
* **Rule Legend** — explanation of each rule identifier
110+
* **Notes** — detailed messages for warnings and failures
111+
112+
### Status Indicators
113+
114+
| Symbol | Meaning |
115+
| ------- | -------------------------------------------------------- |
116+
| Pass | Requirement is met |
117+
| Fail | Requirement is not met (configuration is non-conformant) |
118+
| Warning | Recommended practice is not followed |
119+
| N/A | Rule is not applicable to this configuration |
120+
121+
## Requirements
122+
123+
The conformance report uses `IClientStore.GetAllClientsAsync` to enumerate all clients for
124+
assessment. Custom `IClientStore` implementations must implement this method (added in v8.0).
125+
See the [upgrade guide](/identityserver/upgrades/v7_4-to-v8_0/#iclientstoregettallclientsasync-now-required)
126+
for details.
127+
128+
## Full Example
129+
130+
```csharp
131+
// Program.cs
132+
133+
builder.Services.AddIdentityServer()
134+
.AddInMemoryClients(Config.Clients)
135+
.AddConformanceReport(options =>
136+
{
137+
options.Enabled = true;
138+
options.EnableOAuth21Assessment = true;
139+
options.EnableFapi2SecurityAssessment = true;
140+
options.HostCompanyName = "Acme Corp";
141+
options.ConfigureAuthorization = policy => policy.RequireRole("ComplianceTeam");
142+
});
143+
144+
// ...
145+
146+
app.MapConformanceReport();
147+
app.UseIdentityServer();
148+
```

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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,11 @@ systems (APM). They used to have their own different APIs so IdentityServer only
3333
that could be used to call the APM's APIs. Thanks to OpenTelemetry there is now a standardized
3434
way to emit diagnostic information from a process. The events may eventually be deprecated and removed.
3535

36-
[Read More](/identityserver/diagnostics/events.md)
36+
[Read More](/identityserver/diagnostics/events.md)
37+
38+
## Conformance Report
39+
40+
IdentityServer can generate a conformance report that assesses your configuration against OAuth 2.1
41+
and FAPI 2.0 specifications.
42+
43+
[Read More](/identityserver/diagnostics/conformance-report/)

0 commit comments

Comments
 (0)