Merge branch 'main' into ar/more-specific-isolation

Author: ProgrammerAL

README.md

@@ -216,6 +216,25 @@ redirects: {
 This will remove the old page from the navigation structure, but keeps the URL around
 with a redirect to the new location.
 
+## 🤖 AI-Friendly Documentation
+
+We make our docs consumable by AI agents and LLMs, not just humans.
+
+### What we do
+
+* **[`llms.txt`](https://docs.duendesoftware.com/llms.txt) and [`llms-full.txt`](https://docs.duendesoftware.com/llms-full.txt)** — Machine-readable site index and full content dump following the [llms.txt proposal](https://llmstxt.org/), so AI tools can discover and ingest our docs.
+* **Content negotiation** — The server supports `Accept: text/markdown` to return raw Markdown for any docs page, giving AI agents clean content without HTML noise.
+* **`robots.txt` signals** — We don't block AI crawlers. The robots.txt includes references to `llms.txt` so crawlers can find structured content.
+
+Beyond this repo, Duende also provides tools that give AI coding assistants specialized knowledge (see [AI Agent Tools](https://docs.duendesoftware.com/general/ai-agent-tools/)):
+
+* **[Agent Skills](https://github.com/DuendeSoftware/duende-skills)** — Structured `SKILL.md` files following the [Agent Skills format](https://agentskills.io/) that give AI assistants domain expertise on IdentityServer, BFF, token management, and more. Loaded automatically by compatible IDEs.
+* **[MCP Server](https://github.com/DuendeSoftware/products/blob/main/docs-mcp/README.md)** — A local [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants search and fetch access to the full Duende docs, blog, and sample code via SQLite full-text search.
+
+### Why
+
+Developers increasingly use AI assistants to find answers. If our docs aren't AI-friendly, those assistants hallucinate or point elsewhere. Making content machine-readable means Duende products get accurate representation in AI-generated answers.
+
 ## ⚖️ License
 
 For all licensing information, refer to the relevant license files:

astro/astro.config.mjs

@@ -17,6 +17,7 @@ import * as fs from "node:fs";
 import { duendeOpenGraphImage } from "./src/plugins/duende-og-image.js";
 import removeMarkdownExtensions from "./src/plugins/remove-markdown-extensions.js";
 import staticRedirects from "./src/plugins/static-redirects.js";
+import markdownOutput from "./src/plugins/markdown-output.js";
 
 // https://astro.build/config
 export default defineConfig({
@@ -233,6 +234,7 @@ export default defineConfig({
       contentDir: "./src/content/docs",
     }),
     staticRedirects(),
+    markdownOutput(),
     opengraphImages({
       options: {
         fonts: [

astro/package-lock.json

@@ -34,10 +34,13 @@
     "astro-opengraph-images": "^1.14.3",
     "astro-redirect-from": "^1.3.5",
     "astro-rehype-relative-markdown-links": "^0.19.0",
+    "hast-util-to-text": "^4.0.2",
     "jsdom": "^29.0.2",
     "patch-package": "^8.0.1",
     "react": "^19.2.4",
     "rehype-external-links": "^3.0.0",
+    "rehype-parse": "^9.0.1",
+    "rehype-remark": "^10.0.1",
     "satori": "^0.26.0",
     "sharp": "^0.34.5",
     "starlight-auto-sidebar": "^0.2.0",

astro/package.json

@@ -1,4 +1,5 @@
 User-agent: *
+Content-Signal: ai-train=yes, search=yes, ai-input=yes
 Allow: /
 
-Sitemap: https://docs.duendesoftware.com/sitemap-index.xml
+Sitemap: https://docs.duendesoftware.com/sitemap-index.xml

astro/public/robots.txt

@@ -16,7 +16,36 @@ redirect_from:
   - /identityserver/v7/configuration/dcr/installation/
 ---
 
-import { Steps } from "@astrojs/starlight/components";
+import { Code, Steps } from "@astrojs/starlight/components";
+
+export const addMainPackageSnippet = `
+cd Configuration
+dotnet add package Duende.IdentityServer.Configuration
+`;
+
+export const addStoragePackageSnippet = `dotnet add package Duende.IdentityServer.Configuration.EntityFramework`;
+
+export const licenseSnippet = `
+builder.Services.AddIdentityServerConfiguration(opt =>
+    opt.LicenseKey = "<license>";
+);
+`;
+
+export const dbConfigurationSnippet = `
+builder.Services.AddIdentityServerConfiguration(opt =>
+    opt.LicenseKey = "<license>"
+).AddClientConfigurationStore();` + '\r\n' + `
+var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
+builder.Services.AddConfigurationDbContext<ConfigurationDbContext>(options =>
+{
+    options.ConfigureDbContext = builder => builder.UseSqlite(connectionString);
+});
+`;
+
+export const mapDcrEndpointSnippet = `
+app.MapDynamicClientRegistration()
+    .RequireAuthorization("DCR");
+`;
 
 Dynamic Client Registration (DCR) is the process of registering OAuth clients
 dynamically. It allows OAuth client applications to programmatically register
@@ -53,31 +82,24 @@ To host the Configuration API separately from IdentityServer, you will need to
 create a new ASP.NET Core Web application which will host the Configuration API.
 
 <Steps>
+
 1. **Create a new project of type "Empty Web Application"**
 
     ```bash title=Terminal
     dotnet new web -n Configuration
     ```
 
 2. **Add the `Duende.IdentityServer.Configuration` package**
-    
-    ```bash title=Terminal
-    cd Configuration
-    dotnet add package Duende.IdentityServer.Configuration
-    ```
-   
+
+    <Code code={addMainPackageSnippet} lang="bash" title="Terminal" />
+
 3. **Configure services to include the Configuration API**
-    
-    ```csharp
-    // Program.cs
-    builder.Services.AddIdentityServerConfiguration(opt =>
-        opt.LicenseKey = "<license>";
-    );
-    ```
+
+    <Code code={licenseSnippet} lang="csharp" title="Program.cs" />
 
     :::note
     This feature is part of the [Duende IdentityServer Business and Enterprise Edition](https://duendesoftware.com/products/identityserver).
-    Configure the same license key for IdentityServer and the Configuration API.
+    You don't need to acquire an additional license, use the same license key for Duende IdentityServer and the DCR Configuration API.
     :::
 
 4. **Add and configure the client configuration store**
@@ -90,43 +112,27 @@ create a new ASP.NET Core Web application which will host the Configuration API.
     the interface yourself. See [the IClientConfigurationStore reference](/identityserver/reference/stores/index.md)
     for more details. If you wish to use the built-in implementation, install its NuGet
     package and add it to the ASP.NET Core service provider.
-    
-    ```bash title=Terminal
-    dotnet add package Duende.IdentityServer.Configuration.EntityFramework
-    ```
+
+    <Code code={addStoragePackageSnippet} lang="bash" title="Terminal" />
 
     The `AddClientConfigurationStore()` extension method registers the built-in
     implementation of the `IClientConfigurationStore` interface with the service
     provider. Make sure to also configure the connection string to the
     [configuration store](/identityserver/data/ef.md#configuration-store-support):
 
-    ```csharp {4}
-    // Program.cs
-    builder.Services.AddIdentityServerConfiguration(opt =>
-        opt.LicenseKey = "<license>"
-    ).AddClientConfigurationStore();
-    
-    var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
-    builder.Services.AddConfigurationDbContext<ConfigurationDbContext>(options =>
-    {
-        options.ConfigureDbContext = builder => builder.UseSqlite(connectionString);
-    });
-    ```
-   
+    <Code code={dbConfigurationSnippet} lang="csharp" title="Program.cs" mark={[3]} />
+
 5. **Map the Configuration API endpoints**
-    
-    ```csharp
-    // Program.cs
-    app.MapDynamicClientRegistration()
-       .RequireAuthorization("DCR");
-    ```
-    
+
+    <Code code={mapDcrEndpointSnippet} lang="csharp" title="Program.cs" />
+
     The `MapDynamicClientRegistration` extension method registers the DCR endpoints
     and returns an `IEndpointConventionBuilder` which you can use to define authorization
     requirements for your DCR endpoint.
 
     See [Authorization](#authorization) for more details about implementing authorization for
     the DCR endpoint.
+
 </Steps>
 
 ### Shared Host For Configuration API and IdentityServer
@@ -136,26 +142,18 @@ You'll need to add the Configuration API's services to the service collection,
 and configure the store implementation.
 
 <Steps>
+
 1. **Add the `Duende.IdentityServer.Configuration` package**
 
-    ```bash title=Terminal
-    cd Configuration
-    dotnet add package Duende.IdentityServer.Configuration
-    ```
+    <Code code={addMainPackageSnippet} lang="bash" title="Terminal" />
 
 2. **Configure services to include the Configuration API**
 
-    ```csharp
-    // Program.cs
-    builder.Services.AddIdentityServerConfiguration(opt =>
-        opt.LicenseKey = "<license>";
-    );
-    ```
+    <Code code={licenseSnippet} lang="csharp" title="Program.cs" />
 
     :::note
-    The Configuration API feature is included in the Duende IdentityServer Business
-    edition license and higher. Use the same license key for IdentityServer and the
-    Configuration API.
+    This feature is part of the [Duende IdentityServer Business and Enterprise Edition](https://duendesoftware.com/products/identityserver).
+    You don't need to acquire an additional license, use the same license key for Duende IdentityServer and the DCR Configuration API.
     :::
 
 3. **Add and configure the client configuration store**
@@ -169,45 +167,69 @@ and configure the store implementation.
     for more details. If you wish to use the built-in implementation, install its NuGet
     package and add it to the ASP.NET Core service provider.
 
-    ```bash title=Terminal
-    dotnet add package Duende.IdentityServer.Configuration.EntityFramework
-    ```
+    <Code code={addStoragePackageSnippet} lang="bash" title="Terminal" />
 
     The `AddClientConfigurationStore()` extension method registers the built-in
     implementation of the `IClientConfigurationStore` interface with the service
     provider. Make sure to also configure the connection string to the
     [configuration store](/identityserver/data/ef.md#configuration-store-support) if
     you haven't already as part of your IdentityServer host:
 
-    ```csharp {4}
-    // Program.cs
-    builder.Services.AddIdentityServerConfiguration(opt =>
-        opt.LicenseKey = "<license>"
-    ).AddClientConfigurationStore();
-    
-    var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
-    builder.Services.AddConfigurationDbContext<ConfigurationDbContext>(options =>
-    {
-        options.ConfigureDbContext = builder => builder.UseSqlite(connectionString);
-    });
-    ```
+    <Code code={dbConfigurationSnippet} lang="csharp" title="Program.cs" mark={[3]} />
 
 4. **Map the Configuration API endpoints**
 
-    ```csharp
-    // Program.cs
-    app.MapDynamicClientRegistration()
-       .RequireAuthorization("DCR");
-    ```
+    <Code code={mapDcrEndpointSnippet} lang="csharp" title="Program.cs" />
 
     The `MapDynamicClientRegistration` extension method registers the DCR endpoints
     and returns an `IEndpointConventionBuilder` which you can use to define authorization
     requirements for your DCR endpoint.
 
     See [Authorization](#authorization) for more details about implementing authorization for
     the DCR endpoint.
+
 </Steps>
 
+### Adding the Registration Endpoint to the Discovery Document
+
+By default, the Dynamic Client Registration (DCR) endpoint is not included in the [discovery document](/identityserver/reference/endpoints/discovery.md) of Duende IdentityServer.
+
+To include it, change the Discovery Document options when registering IdentityServer in the service collection:
+
+```csharp
+// Program.cs
+builder.Services.AddIdentityServer(options =>
+{
+    // Either use a static URL for the registration endpoint, when hosted outside of IdentityServer:
+    options.Discovery.DynamicClientRegistration.RegistrationEndpointMode =
+        RegistrationEndpointMode.Static;
+
+    options.Discovery.DynamicClientRegistration.StaticRegistrationEndpoint =
+        new Uri("https://my-configuration-api/connect/dcr");
+
+    // Or use inferred when the registration endpoint is hosted within IdentityServer:
+    options.Discovery.DynamicClientRegistration.RegistrationEndpointMode =
+        RegistrationEndpointMode.Inferred;
+});
+```
+
+:::note
+DCR support was added to Duende IdentityServer v7.4. If you cannot upgrade your IdentityServer solution yet,
+you'll have to add custom entries to the Discovery Document instead:
+
+```csharp
+// Program.cs
+using Duende.IdentityModel;
+
+builder.Services.AddIdentityServer(options =>
+{
+    options.Discovery.CustomEntries.Add
+        OidcConstants.Discovery.RegistrationEndpoint,
+        "https://my-configuration-api/connect/dcr");
+});
+```
+:::
+
 ## Authorization
 
 When implementing Dynamic Client Registration (DCR), it is important to consider
@@ -339,4 +361,4 @@ For more details, see the [reference section on DCR request processing](/identit
 To customize the HTTP responses of the Configuration API, you can implement the `IDynamicClientRegistrationResponseGenerator`
 interface, or extend the default `DynamicClientRegistrationResponseGenerator`.
 
-For more details, see the [reference section on rDCR esponse generation](/identityserver/reference/dcr/response.md).
+For more details, see the [reference section on DCR response generation](/identityserver/reference/dcr/response.md).

astro/src/content/docs/identityserver/configuration/dcr.mdx

@@ -78,7 +78,7 @@ depending on your needs)
 and add the IdentityServer middleware to that application. The middleware adds the necessary protocol heads to the
 application so that clients can talk to it using those standard protocols.
 
-![IdentityServer middleware diagram and its relatinship in the ASP.NET Core pipeline](images/middleware.svg)
+![IdentityServer middleware diagram and its relationship in the ASP.NET Core pipeline](images/middleware.svg)
 
 The hosting application can be as complex as you want, but we typically recommend to keep the attack surface as small as
 possible by including

astro/src/content/docs/identityserver/overview/big-picture.md

@@ -125,7 +125,7 @@ Add the following to `src/JavaScriptClient/Program.cs`:
             options.SaveTokens = true;
             options.GetClaimsFromUserInfoEndpoint = true;
             options.MapInboundClaims = false;
-        }
+        })
         .ConfigureCookies(options => options.Cookie.SameSite = SameSiteMode.Strict)
         .AddRemoteApis();
 

astro/src/content/docs/identityserver/quickstarts/javascript-clients/js-with-backend.mdx

@@ -1,3 +1,3 @@
 {
-  "content": "<strong>New Livestream:</strong> A First Look at Duende's First-Party SAML 2.0 Support. <a href=\"https://duendesoftware.com/webinars/first-look-at-duende-first-party-saml-2-0-support\">Register Now!</a>"
+  "content": ""
 }