Merge pull request #818 from DuendeSoftware/wca/introspection-foss-docs

wcabus · web-flow · commit 396eb4b90aa9 · 2025-09-08T16:09:38.000+02:00
Added docs for the OAuth2introspection library
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -214,6 +214,12 @@ export default defineConfig({
           autogenerate: { directory: "identitymodel-oidcclient" },
           collapsed: true,
         },
+        {
+          label: "Introspection for ASP.NET Core",
+          badge: "oss",
+          autogenerate: { directory: "introspection" },
+          collapsed: true,
+        },
       ],
     }),
     redirectFrom({
diff --git a/src/content/docs/identityserver/apis/aspnetcore/reference.md b/src/content/docs/identityserver/apis/aspnetcore/reference.md
@@ -13,9 +13,10 @@ redirect_from:
 
 If you are using [reference tokens](/identityserver/tokens/reference.md), you need an authentication handler that
 implements the back-channel validation via the [OAuth 2.0 token introspection](https://tools.ietf.org/html/rfc7662)
-protocol, e.g. [this](https://github.com/IdentityModel/IdentityModel.AspNetCore.OAuth2Introspection) one:
+protocol, e.g. [Duende.AspNetCore.Authentication.OAuth2Introspection](/introspection/index.mdx):
 
-```cs
+```csharp
+// Program.cs
 builder.Services.AddAuthentication("token")
     .AddOAuth2Introspection("token", options =>
     {
@@ -32,7 +33,8 @@ builder.Services.AddAuthentication("token")
 It is not uncommon to use the same API with both JWTs and reference tokens. In this case you set up two authentication
 handlers, make one the default handler and provide some forwarding logic, e.g.:
 
-```cs
+```csharp
+// Program.cs
 builder.Services.AddAuthentication("token")
 
     // JWT tokens
@@ -59,7 +61,8 @@ builder.Services.AddAuthentication("token")
 
 The logic of the forward selector looks like this:
 
-```cs
+```csharp
+// IntrospectionUtilities.cs
 /// <summary>
 /// Provides a forwarding func for JWT vs reference tokens (based on existence of dot in token)
 /// </summary>
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
@@ -33,8 +33,6 @@ import {
   Badge,
 } from "@astrojs/starlight/components";
 import Newsletter from "~/components/Newsletter.astro";
-import TestimonialGrid from "~/components/testimonial-grid.astro";
-import Testimonial from "~/components/testimonial.astro";
 
 <CardGrid>
     <Card title="Install templates" icon="rocket">
@@ -93,6 +91,12 @@ import Testimonial from "~/components/testimonial.astro";
       Learn more
     </LinkButton>
   </Card>
+  <Card title="Introspection for ASP.NET Core" icon="github">
+    <Badge text={"OSS"} /> ASP.NET Core authentication handler for OAuth 2.0 token introspection.
+    <LinkButton href="/introspection/" variant="secondary">
+      Learn more
+    </LinkButton>
+  </Card>
 </CardGrid>
 
 <hr />
diff --git a/src/content/docs/introspection/index.mdx b/src/content/docs/introspection/index.mdx
@@ -0,0 +1,106 @@
+---
+title: Duende Introspection Authentication Handler
+description: An ASP.NET Core authentication handler for OAuth 2.0 token introspection.
+sidebar:
+  label: Overview
+  order: 1
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
+
+The `Duende.AspNetCore.Authentication.OAuth2Introspection` library implements an ASP.NET Core authentication handler for
+OAuth 2.0 token introspection, as defined in [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662), "OAuth 2.0 Token Introspection".
+
+## Use Case
+
+Using this library, you can request information about access tokens from an authorization server, allowing your
+ASP.NET Core application to validate tokens and retrieve metadata about them. This enables you to use opaque tokens in
+your application, where the token itself does not carry any information about the user or the scopes granted, but instead
+relies on the authorization server to provide this information.
+
+:::tip
+By default, you can also use this library to introspect JWT tokens.
+You can disable this behavior by setting `SkipTokensWithDots = true` in the [`OAuth2IntrospectionOptions`](/introspection-auth-handler/options.mdx).
+:::
+
+## Features
+
+- Implements the OAuth 2.0 token introspection protocol
+- Supports both opaque and JWT access token introspection
+- Supports caching of introspection results to reduce load on the authorization server
+- Provides a customizable authentication handler for ASP.NET Core
+- Integrates seamlessly with ASP.NET Core's authentication middleware
+
+## Installation
+
+If you want to use the `Duende.AspNetCore.Authentication.OAuth2Introspection` library, you need to add the NuGet package
+to your ASP.NET Core project.
+
+You can achieve this by running the following command in your terminal:
+
+```bash
+dotnet package add Duende.AspNetCore.Authentication.OAuth2Introspection
+```
+
+## Configuration
+
+To configure the OAuth 2.0 token introspection handler in your ASP.NET Core application, you need to add it to the
+authentication services in your `Startup.cs` or `Program.cs` file.
+
+Here's an example on how to set it up:
+
+```csharp
+// Program.cs
+using Duende.AspNetCore.Authentication.OAuth2Introspection;
+
+builder.Services.AddAuthentication(OAuth2IntrospectionDefaults.AuthenticationScheme)
+    .AddOAuth2Introspection(options =>
+    {
+        // Replace with your authorization server's URL
+        options.Authority = "https://demo.duendesoftware.com";
+
+        options.ClientId = "client_id_for_introspection_endpoint";
+        options.ClientSecret = "client_secret_for_introspection_endpoint";
+    });
+```
+
+More details on the available options can be found on the [options page](/introspection-auth-handler/options.mdx).
+
+### Configuring the Backchannel HTTP Client
+
+You can configure the HTTP client used by the introspection handler to make requests to the introspection endpoint, for example,
+when your ASP.NET Core application lives behind a proxy or requires specific HTTP client settings.
+
+```csharp
+// Program.cs
+builder.Services.AddHttpClient(OAuth2IntrospectionDefaults.BackchannelHttpClientName)
+    .AddHttpMessageHandler(() =>
+    {
+        // Configure client/handler for the back channel HTTP Client here
+        return new HttpClientHandler
+        {
+            UseProxy = true,
+            Proxy = new WebProxy(WebProxyUri, true)
+        };
+    });
+```
+
+## License and Feedback
+
+`Duende.AspNetCore.Authentication.OAuth2Introspection` is released as open source under the
+[Apache 2.0 license](https://github.com/DuendeSoftware/foss/blob/main/LICENSE).
+Bug reports and contributions are welcome at
+[the GitHub repository](https://github.com/DuendeSoftware/foss).
+
+<CardGrid>
+  <LinkCard
+    href="https://github.com/DuendeSoftware/foss/tree/main/introspection"
+    title="GitHub Repository"
+    description="View the source code for this library on GitHub."
+  />
+  <LinkCard
+    href="https://www.nuget.org/packages/Duende.AspNetCore.Authentication.OAuth2Introspection"
+    title="NuGet Package"
+    description="View the package on NuGet.org."
+  />
+</CardGrid>
diff --git a/src/content/docs/introspection/options.mdx b/src/content/docs/introspection/options.mdx
@@ -0,0 +1,153 @@
+---
+title: Configuring OAuth 2.0 Token Introspection
+description: Learn more about the various options when adding the ASP.NET Core authentication handler for OAuth 2.0 token introspection.
+sidebar:
+  label: Options
+  order: 2
+---
+
+#### OAuth2IntrospectionOptions
+
+`OAuth2IntrospectionOptions` is the options class to configure the ASP.NET Core authentication handler for OAuth 2.0 token introspection.
+
+You set the options when registering the authentication handler at startup time, using a lambda expression in the `AddOAuth2Introspection` method:
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication(OAuth2IntrospectionDefaults.AuthenticationScheme)
+    .AddOAuth2Introspection(options =>
+    {
+        // configure options here...
+    });
+```
+
+## Main
+
+Top-level settings. Available directly on the `OAuth2IntrospectionOptions` class.
+
+* **`Authority`**
+
+The URL of the token server. When configured, the handler will use this URI to discover the introspection endpoint.
+
+* **`IntrospectionEndpoint`**
+
+Sets the URL of the introspection endpoint. If this is set, the `Authority` will not be used to discover the introspection endpoint.
+
+* **`ClientId`**
+
+Specifies the ID of the introspection client. This setting is required.
+
+* **`ClientSecret`**
+
+Specifies the shared secret of the introspection client.
+
+* **`ClientCredentialStyle`**
+
+Specifies how the client credentials are sent to the introspection endpoint. The default is `ClientCredentialStyle.PostBody`, which sends the credentials in the body of the request.
+You can also set this to `ClientCredentialStyle.AuthorizationHeader` to send the credentials in the `Authorization` header as a Basic authentication scheme.
+
+* **`ClientCredentialStyle `**
+
+Specifies how the authorization header is formatted when used. The default is `BasicAuthenticationHeaderStyle.Rfc2617`, which formats the header according to the [original basic authentication spec](https://tools.ietf.org/html/rfc2617#section-2).
+You can also set this to `BasicAuthenticationHeaderStyle.Rfc6749`, which formats the header according to [RFC 6749](https://tools.ietf.org/html/rfc6749#section-2.3.1).
+
+* **`TokenTypeHint`**
+
+Specifies the token type hint of the introspection client. Defaults to `"access_token"`.
+
+* **`NameClaimType`**
+
+Specifies the claim type to use for the name claim. Defaults to `"name"`.
+
+* **`RoleClaimType`**
+
+Specifies the claim type to use for the role claim. Defaults to `"role"`.
+
+* **`AuthenticationType`**
+
+Specifies the authentication type to use for the authenticated identity. If not set, the authentication scheme name is used as the authentication type.
+Defaults to `null`.
+
+* **`DiscoveryPolicy`**
+
+Specifies the policy used for the discovery client.
+
+* **`SkipTokensWithDots`**
+
+Specifies whether to skip tokens that contain dots (`.`) in the introspection request. Defaults to `false`.
+
+* **`SaveToken`**
+
+Specifies whether the token should be stored in the context, so it is available for the duration of the HTTP request. Defaults to `true`.
+
+* **`EnableCaching`**
+
+Specifies whether the outcome of the token validation should be cached.
+
+This reduces the number of requests to the introspection endpoint, improving performance and reducing load on the authorization server.
+Defaults to `false`.
+
+* **`CacheDuration`**
+
+Specifies for how long the outcome of the token validation should be cached. Defaults to `TimeSpan.FromMinutes(5)`.
+
+* **`CacheKeyPrefix`**
+
+Specifies the prefix to use for the cache key. Defaults to `string.Empty`.
+
+* **`CacheKeyGenerator`**
+
+Specifies the method to use for generating the cache key.
+Defaults to `CacheUtils.CacheKeyFromToken`, which generates a cache key using the configured `CacheKeyPrefix` combined with the SHA-256 hash from the token.
+
+* **`TokenRetriever`**
+
+Specifies the method to use for retrieving the token from the HTTP request.
+
+Defaults to `TokenRetrieval.FromAuthorizationHeader`, which retrieves the token from the `Authorization` header.
+You can also set this to `TokenRetrieval.FromQueryString`, which retrieves the token from the query string, or use a custom method.
+
+* **`Events`**
+
+Gets or sets the `OAuth2IntrospectionEvents` instance used to handle authentication events.
+
+## Events
+
+The `OAuth2IntrospectionEvents` class allows you to handle various events during the authentication process.
+You can override methods to customize the behavior of the authentication handler, or set custom logic for specific events like `OnTokenValidated`, `OnAuthenticationFailed`, etc.
+
+* **`OnTokenValidated`**
+
+This event is triggered when the token has been successfully validated. You can use this to add additional claims or perform custom logic after the token validation.
+
+* **`OnAuthenticationFailed`**
+
+This event is triggered when exceptions are thrown during request processing. The exceptions will be re-thrown after this event unless suppressed.
+
+* **`OnTokenValidated`**
+
+This event is triggered after the security token has passed validation and a `ClaimsIdentity` has been generated.
+
+* **`OnUpdateClientAssertion`**
+
+This event is triggered when client assertion need to be updated.
+
+* **`OnSendingRequest`**
+
+This event is triggered when sending the token introspection request.
+
+* **`AuthenticationFailed`**
+
+Invoked if exceptions are thrown during request processing. The exceptions will be re-thrown after this event unless suppressed.
+
+* **`TokenValidated`**
+
+Invoked after the security token has passed validation and a ClaimsIdentity has been generated.
+
+* **`UpdateClientAssertion`**
+
+Invoked when client assertion need to be updated.
+
+* **`SendingRequest`**
+
+Invoked when sending the token introspection request.
