Align IdentityServer with products commit 779b24a0dc877dc784fd2f0540c8976c00ef06cd

Author: maartenba

astro/src/content/docs/general/licensing.md

@@ -228,7 +228,7 @@ will cause the host to log an error for every consecutive authenticated session:
 BFF is running in trial mode. The maximum number of allowed authenticated sessions (5) has been exceeded.
 
 See https://duende.link/l/bff/trial for more information. 
-````
+```
 
 The trial mode session limit is not distributed or shared across multiple nodes.
 
@@ -242,9 +242,10 @@ when trial mode is not enough.
 
 ## License Key
 
-The license key can be configured in one of two ways:
+The license key can be configured in one of three ways:
 
 * Via a well-known file on the file system
+* Via `IConfiguration` (for example, `appsettings.json` or environment variables)
 * Programmatically in your startup code
 
 You can also use other configuration sources such as Azure Key Vault, by using the
@@ -281,6 +282,48 @@ MyIdentityServer/
 To verify your `ContentRootPath` at runtime, inspect `builder.Environment.ContentRootPath`.
 :::
 
+### Configuration :badge[v8.0]
+
+
+IdentityServer can read the license key directly from `IConfiguration`, so you do not need to write any startup code.
+If `LicenseKey` is not set in your `AddIdentityServer` call, IdentityServer checks the following configuration keys in order,
+using the first non-empty value it finds:
+
+1. `Duende:IdentityServer:LicenseKey`
+2. `Duende:LicenseKey`
+
+Whitespace is trimmed, and empty or whitespace-only values are ignored.
+
+Add the license key to `appsettings.json` using the IdentityServer-specific key:
+
+```json title="appsettings.json"
+{
+  "Duende": {
+    "IdentityServer": {
+      "LicenseKey": "eyJhbG..."
+    }
+  }
+}
+```
+
+Or use the shorter key:
+
+```json title="appsettings.json"
+{
+  "Duende": {
+    "LicenseKey": "eyJhbG..."
+  }
+}
+```
+
+Because `IConfiguration` supports many providers, you can also supply the key via environment variables
+(for example, `Duende__IdentityServer__LicenseKey` or `Duende__LicenseKey`), Azure App Configuration, Azure Key Vault,
+or any other configuration source.
+
+:::note
+Loading the license key from configuration is not currently supported in Duende BFF.
+:::
+
 ### Startup
 
 If you prefer to load the license key programmatically, you can do so in your startup

astro/src/content/docs/identityserver/diagnostics/data.mdx

@@ -650,6 +650,8 @@ Diagnostics data is written to logs in one or more chunks containing data format
           "ShowTokenEndpointAuthenticationMethods":true,
           "ExpandRelativePathsInCustomEntries":true,
           "ResponseCacheInterval":null,
+          "EnableDiscoveryDocumentCache":false,
+          "DiscoveryDocumentCacheDuration":"00:01:00",
           "CustomEntries":{
 
           }
@@ -911,11 +913,7 @@ Diagnostics data is written to logs in one or more chunks containing data format
           "HS384",
           "HS512"
         ],
-        "Preview":{
-          "EnableDiscoveryDocumentCache":false,
-          "StrictClientAssertionAudienceValidation":false,
-          "DiscoveryDocumentCacheDuration":"00:01:00"
-        },
+        "StrictClientAssertionAudienceValidation":false,
         "Diagnostics":{
           "LogFrequency":"00:10:00",
           "ChunkSize":8160

astro/src/content/docs/identityserver/reference/v8/options.md

@@ -86,6 +86,41 @@ Top-level settings. Available directly on the `IdentityServerOptions` object.
 
   The allowed signature algorithms for client authentication using client assertions (`private_key_jwt`). The `alg` header of client assertions is validated against this collection, and the `token_endpoint_auth_signing_alg_values_supported` discovery property is populated with these values. Defaults to `[RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512]`. If set to an empty collection, all algorithms are allowed but `token_endpoint_auth_signing_alg_values_supported` will not be set.
 
+- **`LicenseKey`**
+
+  The license key for Duende IdentityServer. Set this property to the content of your license key file.
+
+  If you do not set `LicenseKey` in code, IdentityServer automatically reads it from `IConfiguration` at startup.
+  It checks the following configuration keys in order, using the first non-empty value it finds:
+
+  1. `Duende:IdentityServer:LicenseKey`
+  2. `Duende:LicenseKey`
+
+  Whitespace is trimmed, and empty or whitespace-only values are ignored. This means you can supply the license key via `appsettings.json`,
+  environment variables, Azure Key Vault, or any other [configuration provider](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/)
+  without writing any code.
+
+  See the [licensing documentation](/general/licensing.md#license-key) for all supported approaches.
+
+- **`StrictClientAssertionAudienceValidation`**
+
+  When using [private key JWT](/identityserver/tokens/client-authentication.md#private-key-jwts)
+  client authentication, there is a theoretical vulnerability where a relying party trusting
+  multiple OpenID Providers could be attacked if one of those providers is malicious or compromised.
+  The OpenID Foundation proposed a two-part fix: strictly validate the audience and set an explicit
+  `typ` header in the authentication JWT.
+
+  Setting this flag to `true` strictly validates that the audience is equal to the issuer and
+  validates the token's `typ` header, as specified in
+  [RFC 7523 bis](https://datatracker.ietf.org/doc/draft-ietf-oauth-rfc7523bis/). Defaults to
+  `false`.
+
+  When this flag is `false`, validation behavior is determined based on the `typ` header being
+  present. When the token sets the `typ` header to `client-authentication+jwt`, IdentityServer
+  assumes the client's intention is to apply strict audience validation. If `typ` is not present,
+  [default audience validation](/identityserver/apis/aspnetcore/jwt.md#adding-audience-validation)
+  is used.
+
 ## Key management
 
 Automatic key management settings. Available on the `KeyManagement` property of the `IdentityServerOptions` object.
@@ -293,6 +328,21 @@ var idsvrBuilder = builder.Services.AddIdentityServer(options =>
 options.Discovery.CustomEntries.Add("my_custom_endpoint", "~/custom");
 ```
 
+- **`EnableDiscoveryDocumentCache`**
+
+  Enables caching of the discovery document response. In large deployments where many concurrent
+  users consume the [discovery endpoint](/identityserver/reference/v8/endpoints/discovery.md) to
+  retrieve metadata about your IdentityServer, enabling this cache can increase throughput.
+  Defaults to `false`.
+
+  Keep the cache duration low if you use the `CustomEntries` element on the discovery document or
+  implement a custom `IDiscoveryResponseGenerator`.
+
+- **`DiscoveryDocumentCacheDuration`**
+
+  The duration for which the discovery document is cached when `EnableDiscoveryDocumentCache` is
+  `true`. Defaults to 1 minute.
+
 ## Authentication
 
 Login/logout related settings. Available on the `Authentication` property of the `IdentityServerOptions`
@@ -556,7 +606,7 @@ User interaction settings, including urls for pages in the UI, names of paramete
   The collection of OIDC prompt modes supported and that will be published in discovery. By
   default, this includes all values in `Constants.SupportedPromptModes`. If the
   `CreateAccountUrl` option is set, then the "create" value is also included. If additional
-  prompt values are added, a customized [`IAuthorizeInteractionResponseGenerator"`](/identityserver/ui/custom.md) is also required to handle those values.
+  prompt values are added, a customized [`IAuthorizeInteractionResponseGenerator`](/identityserver/ui/custom.md) is also required to handle those values.
 
 ## Caching
 
@@ -737,7 +787,7 @@ Settings for [server-side sessions](/identityserver/ui/server-side-sessions/inde
 - **`InvalidRedirectUriPrefixes`**
 
   Collection of URI scheme prefixes that should never be used as custom URI
-  schemes in the `redirect_uri` passed to tha authorize endpoint or the
+  schemes in the `redirect_uri` passed to the authorize endpoint or the
   `post_logout_redirect_uri` passed to the end_session endpoint. Defaults to
   _["javascript:", "file:", "data:", "mailto:", "ftp:", "blob:", "about:",
   "ssh:", "tel:", "view-source:", "ws:", "wss:"]_.
@@ -787,37 +837,3 @@ Demonstration of Proof-of-Possession settings. Available on the `DPoP` property
 
   Maximum size of diagnostic data log message chunks in kilobytes. Defaults to 8160 bytes. 8 KB is a conservative limit for the max size of a log message that is imposed by some logging tools.
   We take 32 bytes less than that to allow for additional formatting of the log message.
-
-## Preview Features
-
-Preview Features settings. Available on the `Preview` property of the `IdentityServerOptions` object.
-
-:::note
-Duende IdentityServer may ship preview features, which can be configured using preview options.
-Note that preview features can be removed and may break in future releases.
-:::
-
-#### Discovery Document Cache
-
-In large deployments of Duende IdentityServer, where a lot of concurrent users attempt to
-consume the [discovery endpoint](/identityserver/reference/v8/endpoints/discovery.md) to retrieve
-metadata about your IdentityServer, you can increase throughput by enabling the
-discovery document cache preview using the _`EnableDiscoveryDocumentCache`_ flag.
-This will cache discovery document information for the duration specified in the
-_`DiscoveryDocumentCacheDuration`_ option.
-
-It's best to keep the cache time low if you use the _`CustomEntries`_ element on the
-discovery document or implement a custom _`IDiscoveryResponseGenerator`_.
-
-#### Strict Audience Validation
-
-When using [_private key JWT_](/identityserver/tokens/client-authentication.md#private-key-jwts),
-there is a theoretical vulnerability where a Relying Party trusting multiple OpenID Providers
-could be attacked if one of the OpenID Providers is malicious or compromised.
-
-The OpenID Foundation proposed a two-part fix: strictly validate the audience and set an
-explicit `typ` header in the authentication JWT.
-
-You can [enable strict audience validation in Duende IdentityServer](/identityserver/tokens/client-authentication.md#strict-audience-validation)
-using the _`StrictClientAssertionAudienceValidation`_ flag, which strictly validates that
-the audience is equal to the issuer and validates the token's `typ` header.

astro/src/content/docs/identityserver/reference/v8/response-handling/http-response-writer.md

@@ -13,6 +13,12 @@ The `IHttpResponseWriter` interface is the contract for services that can produc
 This is a low level abstraction that is intended to be used if you need to customize the serialization, encoding, or
 HTTP headers in a response from a protocol endpoint.
 
+IdentityServer ships a concrete implementation, `AuthorizeInteractionPageHttpWriter`, that handles redirects to login,
+consent, create-account, and custom interaction pages. It is public and designed to be subclassed: you can override
+`BuildReturnUrlAsync`, `BuildRedirectUrlAsync`, or `WriteResponseAsync` to change how those redirects are constructed
+and delivered. See [Customizing authorize interaction redirects](/identityserver/ui/custom-redirect.md) for a how-to
+guide and code examples.
+
 #### Duende.IdentityServer.Hosting.IHttpResponseWriter
 
 ```csharp

astro/src/content/docs/identityserver/tokens/client-authentication.md

@@ -396,16 +396,20 @@ a victim OpenID Provider.
 The OpenID Foundation proposed a two-part fix: strictly validate the audience and set an
 explicit `typ` header (with value `client-authentication+jwt`) in the authentication JWT.
 
-You can enable strict audience validation using the [
-*`StrictClientAssertionAudienceValidation`*](/identityserver/reference/v8/options.md#strict-audience-validation)
-flag, which always strictly validates that the audience is equal to the issuer and validates the token's
+You can enable strict audience validation by setting [`StrictClientAssertionAudienceValidation`](/identityserver/reference/v8/options.md#main)
+to `true`. When enabled, IdentityServer strictly validates that the audience is equal to the issuer identifier and validates the token's
 `typ` header, as specified in [RFC 7523 bis](https://datatracker.ietf.org/doc/draft-ietf-oauth-rfc7523bis/).
 
-When *`StrictClientAssertionAudienceValidation`* is not enabled, validation behavior is determined based
+`StrictClientAssertionAudienceValidation` defaults to `false`. When `false`, IdentityServer accepts the following legacy audience values in addition to the issuer identifier:
+
+* The token endpoint URL
+* The CIBA endpoint URL
+* The PAR endpoint URL
+
+When `StrictClientAssertionAudienceValidation` is `false`, validation behavior is also determined based
 on the `typ` header being present. When the token sets the `typ` header to `client-authentication+jwt`,
 IdentityServer assumes the client's intention is to apply strict audience validation.
-If `typ` is not
-present, [default audience validation](/identityserver/apis/aspnetcore/jwt.md#adding-audience-validation)
+If `typ` is not present, [default audience validation](/identityserver/apis/aspnetcore/jwt.md#adding-audience-validation)
 is used.
 
 ### Mutual TLS Client Certificates

astro/src/content/docs/identityserver/ui/custom-redirect.md

@@ -0,0 +1,111 @@
+---
+title: "Customizing authorize interaction redirects"
+description: "How to subclass AuthorizeInteractionPageHttpWriter to customize how IdentityServer redirects users to login, consent, and other interaction pages."
+date: 2026-05-08
+sidebar:
+  label: "Custom redirect writer"
+  order: 55
+---
+
+When IdentityServer needs to send a user to an interaction page, like login, consent, create-account, or a [custom page](/identityserver/ui/custom.md),
+it builds a redirect URL and writes an HTTP 303 response. The class responsible for this is `AuthorizeInteractionPageHttpWriter`, which is public and designed to be subclassed.
+
+You might want to customize this behavior to:
+
+* Set a cookie before the redirect (for example, to carry state that survives the round-trip through the interaction page).
+* Append a custom query parameter to the interaction page URL (for example, a tenant identifier or a UI hint).
+* Change the redirect status code or add extra response headers.
+
+## How it works
+
+`AuthorizeInteractionPageHttpWriter` implements `IHttpResponseWriter<AuthorizeInteractionPageResult>` and exposes three virtual methods you can override independently:
+
+| Method                  | Responsibility                                                      |
+|-------------------------|---------------------------------------------------------------------|
+| `BuildReturnUrlAsync`   | Builds the URL that points back to the authorize callback endpoint. |
+| `BuildRedirectUrlAsync` | Combines the interaction page URL with the return URL.              |
+| `WriteResponseAsync`    | Writes the HTTP response (status code, `Location` header).          |
+
+The default `WriteHttpResponse` implementation calls all three in sequence. You only need to override the method that covers the behavior you want to change.
+
+## Example: appending a custom query parameter
+
+The example below adds a `ui_hint` query parameter to every redirect URL so the interaction page can adjust its appearance based on the originating client.
+
+```csharp
+// CustomRedirectWriter.cs
+using Duende.IdentityServer.Configuration;
+using Duende.IdentityServer.Endpoints.Results;
+using Duende.IdentityServer.Hosting;
+using Duende.IdentityServer.Services;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Primitives;
+
+public class CustomRedirectWriter : AuthorizeInteractionPageHttpWriter
+{
+    public CustomRedirectWriter(
+        IdentityServerOptions options,
+        IServerUrls urls,
+        IUiLocalesService localesService,
+        IAuthorizationParametersMessageStore? authorizationParametersMessageStore = null)
+        : base(options, urls, localesService, authorizationParametersMessageStore)
+    {
+    }
+
+    protected override async Task<string> BuildRedirectUrlAsync(
+        AuthorizeInteractionPageResult result,
+        string returnUrl,
+        HttpContext context)
+    {
+        var redirectUrl = await base.BuildRedirectUrlAsync(result, returnUrl, context);
+
+        // Append a ui_hint parameter so the interaction page knows which client triggered the flow.
+        var clientId = result.Request?.ClientId;
+        if (!string.IsNullOrEmpty(clientId))
+        {
+            redirectUrl += (redirectUrl.Contains('?') ? "&" : "?")
+                + "ui_hint=" + Uri.EscapeDataString(clientId);
+        }
+
+        return redirectUrl;
+    }
+}
+```
+
+## Example: setting a cookie before the redirect
+
+Override `WriteResponseAsync` when you need to write response headers or cookies in addition to the redirect itself.
+
+```csharp
+// CookieRedirectWriter.cs
+protected override Task WriteResponseAsync(HttpContext context, string redirectUrl)
+{
+    // Set a short-lived cookie that the interaction page can read.
+    context.Response.Cookies.Append("idsrv.hint", "active", new CookieOptions
+    {
+        HttpOnly = true,
+        Secure = true,
+        SameSite = SameSiteMode.Lax,
+        MaxAge = TimeSpan.FromMinutes(5)
+    });
+
+    return base.WriteResponseAsync(context, redirectUrl);
+}
+```
+
+## Registering your writer
+
+Register your subclass using `AddHttpWriter<TResult, TWriter>()` in your IdentityServer setup:
+
+```csharp
+// Program.cs
+builder.Services.AddIdentityServer()
+    .AddHttpWriter<AuthorizeInteractionPageResult, CustomRedirectWriter>();
+```
+
+This replaces the default `AuthorizeInteractionPageHttpWriter` for `AuthorizeInteractionPageResult` responses. All other result types keep their default writers.
+
+:::note
+The return URL built by `BuildReturnUrlAsync` points back into the authorize endpoint. Validate it using the [interaction service](/identityserver/reference/v8/services/interaction-service.md)
+before following it in your interaction page to guard against open-redirect attacks.
+:::

astro/src/content/docs/identityserver/ui/server-side-sessions/index.md

@@ -100,3 +100,10 @@ When listing sessions, prefer `GetSessionsAsync` over `QuerySessionsAsync`.
 The `QuerySessionsAsync` method performs a full-text search and may be slower to retrieve a list of sessions than `GetSessionsAsync`.
 Use `QuerySessionsAsync` only when more advanced filtering is required for the solution you are building.
 :::
+
+### Session Overwrite and Orphaned Grant Cleanup
+
+When a session cookie key is reused by a different user or a new session, IdentityServer automatically revokes the grants that belonged to the previous session.
+This keeps your token store clean and prevents tokens from a prior user's session from remaining valid after the session is overwritten.
+
+See [Session Management](/identityserver/ui/server-side-sessions/session-management.md#orphaned-grant-revocation-on-session-overwrite) for details.

astro/src/content/docs/identityserver/ui/server-side-sessions/session-management.md

@@ -106,3 +106,17 @@ await _sessionManagementService.RemoveSessionsAsync(new RemoveSessionsContext {
 ```
 
 Internally this uses the `IServerSideTicketStore`, `IPersistedGrantStore` and `IBackChannelLogoutService` features from IdentityServer.
+
+## Orphaned Grant Revocation on Session Overwrite
+
+When a session cookie key is reused by a different user or a new session (that is, the subject ID or session ID stored in the cookie
+no longer matches what is in the server-side store), IdentityServer automatically revokes the grants that belonged to the previous
+session before writing the new one. The grants revoked are:
+
+* refresh tokens
+* reference tokens
+* authorization codes
+* backchannel authentication requests
+
+This prevents tokens from a previous user's session from remaining valid after the session is overwritten. Without this cleanup,
+a user whose session was silently replaced could retain working tokens even though their session no longer exists in the store.