Skip to content

Commit fd11934

Browse files
wcabuswcabus
committed
First draft of OAuth2Introspection docs
1 parent 0f0fbba commit fd11934

File tree

4 files changed

+269
-0
lines changed

4 files changed

+269
-0
lines changed

‎astro.config.mjs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,12 @@ export default defineConfig({
163163
autogenerate: { directory: "identitymodel-oidcclient" },
164164
collapsed: true,
165165
},
166+
{
167+
label: "IdentityModel.AspNetCore.\r\nOAuth2Introspection",
168+
badge: "oss",
169+
autogenerate: { directory: "identitymodel-oauth2introspection" },
170+
collapsed: true,
171+
},
166172
],
167173
}),
168174
redirectFrom({

‎src/content/docs/identitymodel-oauth2introspection/index.mdx

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Duende IdentityModel OAuth 2.0 Token Introspection
3+
description: An ASP.NET Core authentication handler for OAuth 2.0 token introspection.
4+
sidebar:
5+
label: Overview
6+
order: 1
7+
---
8+
9+
import { CardGrid, LinkCard } from "@astrojs/starlight/components";
10+
11+
The `Duende.IdentityModel.AspNetCore.OAuth2Introspection` library implements an ASP.NET Core authentication handler for
12+
OAuth 2.0 token introspection, as defined in [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662), "OAuth 2.0 Token Introspection".
13+
14+
## Use Case
15+
16+
Using this library, you can request information about access tokens from an authorization server, allowing your
17+
ASP.NET Core application to validate tokens and retrieve metadata about them. This enables you to use opaque tokens in
18+
your application, where the token itself does not carry any information about the user or the scopes granted, but instead
19+
relies on the authorization server to provide this information.
20+
21+
:::tip
22+
You can also use this library to introspect JWT tokens, by disabling `SkipTokensWithDots` in the `OAuth2IntrospectionOptions`.
23+
This is disabled by default.
24+
:::
25+
26+
## Features
27+
28+
- Implements the OAuth 2.0 token introspection protocol.
29+
- Supports both opaque and JWT access token introspection.
30+
- TODO: does it support introspection of refresh tokens?
31+
- Supports caching of introspection results to reduce load on the authorization server.
32+
- Provides a customizable authentication handler for ASP.NET Core.
33+
- Integrates seamlessly with ASP.NET Core's authentication middleware.
34+
35+
## Installation
36+
37+
To use the `Duende.IdentityModel.AspNetCore.OAuth2Introspection` library, you need to add the NuGet package to your ASP.NET Core project.
38+
You can do this by running the following command in your terminal:
39+
40+
```bash
41+
dotnet package add Duende.IdentityModel.AspNetCore.OAuth2Introspection
42+
```
43+
44+
## Configuration
45+
46+
To configure the OAuth 2.0 token introspection handler in your ASP.NET Core application, you need to add it to the
47+
authentication services in your `Startup.cs` or `Program.cs` file.
48+
49+
Here's an example of how to set it up:
50+
51+
```csharp
52+
// Program.cs
53+
using Duende.IdentityModel.AspNetCore.OAuth2Introspection;
54+
55+
builder.Services.AddAuthentication(OAuth2IntrospectionDefaults.AuthenticationScheme)
56+
.AddOAuth2Introspection(options =>
57+
{
58+
options.Authority = "https://demo.duendesoftware.com"; // Replace with your authorization server's URL
59+
60+
options.ClientId = "client_id_for_introspection_endpoint";
61+
options.ClientSecret = "client_secret_for_introspection_endpoint";
62+
});
63+
```
64+
65+
More details on the available options can be found on the [options page](/identitymodel-oauth2introspection/options.mdx).
66+
67+
### Configuring the Backchannel HTTP Client
68+
69+
You can configure the HTTP client used by the introspection handler to make requests to the introspection endpoint, for example,
70+
when your ASP.NET Core application lives behind a proxy or requires specific HTTP client settings.
71+
72+
```csharp
73+
// Program.cs
74+
builder.Services.AddHttpClient(OAuth2IntrospectionDefaults.BackchannelHttpClientName)
75+
.AddHttpMessageHandler(() =>
76+
{
77+
// Configure client/handler for the back channel HTTP Client here
78+
return new HttpClientHandler
79+
{
80+
UseProxy = true,
81+
Proxy = new WebProxy(WebProxyUri, true)
82+
};
83+
});
84+
```
85+
86+
## License and Feedback
87+
88+
`Duende.IdentityModel.AspNetCore.OAuth2Introspection` is released as open source under the
89+
[Apache 2.0 license](https://github.com/DuendeSoftware/foss/blob/main/LICENSE).
90+
Bug reports and contributions are welcome at
91+
[the GitHub repository](https://github.com/DuendeSoftware/foss).
92+
93+
<CardGrid>
94+
<LinkCard
95+
href="https://github.com/DuendeSoftware/foss/tree/main/identity-model-introspection"
96+
title="GitHub Repository"
97+
description="View the source code for this library on GitHub."
98+
/>
99+
<LinkCard
100+
href="https://www.nuget.org/packages/Duende.IdentityModel.AspNetCore.OAuth2Introspection/"
101+
title="NuGet Package"
102+
description="View the package on NuGet.org."
103+
/>
104+
</CardGrid>

‎src/content/docs/identitymodel-oauth2introspection/options.mdx

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: Configuring OAuth 2.0 token introspection
3+
description: Learn more about the various options when adding the ASP.NET Core authentication handler for OAuth 2.0 token introspection.
4+
sidebar:
5+
label: Options
6+
order: 2
7+
---
8+
9+
#### OAuth2IntrospectionOptions
10+
11+
`OAuth2IntrospectionOptions` is the options class to configure the ASP.NET Core authentication handler for OAuth 2.0 token introspection.
12+
13+
You set the options when registering the authentication handler at startup time, using a lambda expression in the `AddOAuth2Introspection` method:
14+
15+
```csharp
16+
// Program.cs
17+
builder.Services.AddAuthentication(OAuth2IntrospectionDefaults.AuthenticationScheme)
18+
.AddOAuth2Introspection(options =>
19+
{
20+
// configure options here..
21+
});
22+
```
23+
24+
## Main
25+
26+
Top-level settings. Available directly on the `OAuth2IntrospectionOptions` class.
27+
28+
* **`Authority`**
29+
30+
The URL of the token server. When configured, the handler will use this URI to discover the introspection endpoint.
31+
32+
* **`IntrospectionEndpoint`**
33+
34+
Sets the URL of the introspection endpoint. If this is set, the `Authority` will not be used to discover the introspection endpoint.
35+
36+
* **`ClientId`**
37+
38+
Specifies the ID of the introspection client. This setting is required.
39+
40+
* **`ClientSecret`**
41+
42+
Specifies the shared secret of the introspection client.
43+
44+
* **`ClientCredentialStyle`**
45+
46+
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.
47+
You can also set this to `ClientCredentialStyle.AuthorizationHeader` to send the credentials in the `Authorization` header as a Basic authentication scheme.
48+
49+
* **`ClientCredentialStyle `**
50+
51+
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).
52+
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).
53+
54+
* **`TokenTypeHint`**
55+
56+
Specifies the token type hint of the introspection client. Defaults to `"access_token"`.
57+
58+
* **`NameClaimType`**
59+
60+
Specifies the claim type to use for the name claim. Defaults to `"name"`.
61+
62+
* **`RoleClaimType`**
63+
64+
Specifies the claim type to use for the role claim. Defaults to `"role"`.
65+
66+
* **`AuthenticationType`**
67+
68+
Specifies the authentication type to use for the authenticated identity. If not set, the authentication scheme name is used as the authentication type.
69+
Defaults to `null`.
70+
71+
* **`DiscoveryPolicy`**
72+
73+
Specifies the policy used for the discovery client.
74+
75+
* **`SkipTokensWithDots`**
76+
77+
Specifies whether to skip tokens that contain dots (`.`) in the introspection request. Defaults to `false`.
78+
79+
* **`SaveToken`**
80+
81+
Specifies whether the token should be stored in the context, so it is available for the duration of the HTTP request. Defaults to `true`.
82+
83+
* **`EnableCaching`**
84+
85+
Specifies whether the outcome of the token validation should be cached.
86+
87+
This reduces the number of requests to the introspection endpoint, improving performance and reducing load on the authorization server.
88+
Defaults to `false`.
89+
90+
* **`CacheDuration`**
91+
92+
Specifies for how long the outcome of the token validation should be cached. Defaults to `TimeSpan.FromMinutes(5)`.
93+
94+
* **`CacheKeyPrefix`**
95+
96+
Specifies the prefix to use for the cache key. Defaults to `string.Empty`.
97+
98+
* **`CacheKeyGenerator`**
99+
100+
Specifies the method to use for generating the cache key.
101+
Defaults to `CacheUtils.CacheKeyFromToken`, which generates a cache key using the configured `CacheKeyPrefix` combined with the SHA-256 hash from the token.
102+
103+
* **`TokenRetriever`**
104+
105+
Specifies the method to use for retrieving the token from the HTTP request.
106+
107+
Defaults to `TokenRetrieval.FromAuthorizationHeader`, which retrieves the token from the `Authorization` header.
108+
You can also set this to `TokenRetrieval.FromQueryString`, which retrieves the token from the query string, or use a custom method.
109+
110+
* **`Events`**
111+
112+
Gets or sets the `OAuth2IntrospectionEvents` instance used to handle authentication events.
113+
114+
## Events
115+
116+
The `OAuth2IntrospectionEvents` class allows you to handle various events during the authentication process.
117+
You can override methods to customize the behavior of the authentication handler, or set custom logic for specific events like `OnTokenValidated`, `OnAuthenticationFailed`, etc.
118+
119+
* **`OnTokenValidated`**
120+
121+
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.
122+
123+
* **`OnAuthenticationFailed`**
124+
125+
This event is triggered when exceptions are thrown during request processing. The exceptions will be re-thrown after this event unless suppressed.
126+
127+
* **`OnTokenValidated`**
128+
129+
This event is triggered after the security token has passed validation and a `ClaimsIdentity` has been generated.
130+
131+
* **`OnUpdateClientAssertion`**
132+
133+
This event is triggered when client assertion need to be updated.
134+
135+
* **`OnSendingRequest`**
136+
137+
This event is triggered when sending the token introspection request.
138+
139+
* **`AuthenticationFailed`**
140+
141+
Invoked if exceptions are thrown during request processing. The exceptions will be re-thrown after this event unless suppressed.
142+
143+
* **`TokenValidated`**
144+
145+
Invoked after the security token has passed validation and a ClaimsIdentity has been generated.
146+
147+
* **`UpdateClientAssertion`**
148+
149+
Invoked when client assertion need to be updated.
150+
151+
* **`SendingRequest`**
152+
153+
Invoked when sending the token introspection request.

‎src/content/docs/index.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,12 @@ import Testimonial from "~/components/testimonial.astro";
8989
Learn more
9090
</LinkButton>
9191
</Card>
92+
<Card title="OAuth 2.0 Introspection" icon="github">
93+
<Badge text={"OSS"} /> .NET library to use OAuth 2.0 introspection in ASP.NET Core.
94+
<LinkButton href="/identitymodel-oauth2introspection/" variant="secondary">
95+
Learn more
96+
</LinkButton>
97+
</Card>
9298
</CardGrid>
9399

94100
<hr />

0 commit comments

Comments
 (0)