Merge branch 'main' into markdown-extensions-support

Author: khalidabuhakmeh

.idea/docs.duendesoftware.com.iml

@@ -57,7 +57,7 @@ services.AddClientCredentialsTokenManagement()
 Once the key has been configured for the client, then the library will use it to produce a DPoP proof token when calling the token server (including token renewals if relevant).
 There is nothing explicit needed on behalf of the developer using this library.
 
-### `dpop_jkt` At The token Server's Authorize Endpoint
+### `dpop_jkt` At The Token Server's Authorize Endpoint
 
 When using DPoP and `AddOpenIdConnectAccessTokenManagement`, this library will also automatically include the `dpop_jkt` parameter to the authorize endpoint.
 

src/content/docs/accesstokenmanagement/advanced/DPoP.md

@@ -8,9 +8,9 @@ redirect_from:
   - /foss/identitymodel/endpoints/dynamic_registration/
 ---
 
-The client library for [OpenID Connect Dynamic Client
-Registration](https://openid.net/specs/openid-connect-registration-1_0.html)
-is provided as an extension method for *HttpClient*.
+The client library for [OpenID Connect Dynamic Client Registration](https://openid.net/specs/openid-connect-registration-1_0.html)
+is provided as an extension method for [
+`System.Net.Http.HttpClient`](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient).
 
 The following code sends a registration request:
 

src/content/docs/identitymodel/endpoints/dynamic-registration.md

@@ -37,6 +37,9 @@ bytes = WebEncoders.Base64UrlDecode(b64url);
 
 var text = Encoding.UTF8.GetString(bytes); 
 Console.WriteLine(text);
+```
+
+## IdentityModel's Base64Url
 
 IdentityModel includes the *Base64Url* class to help with
 encoding/decoding:

src/content/docs/identitymodel/utils/base64.md

@@ -10,11 +10,17 @@ redirect_from:
   - /identityserver/v7/apis/aspnetcore/confirmation/
 ---
 
-IdentityServer can [bind tokens to clients](/identityserver/tokens/pop.md#proof-of-possession-styles) using either mTLS or DPoP, creating a `Proof-of-Possession` (PoP) access token. When one of these mechanisms is used, APIs that use those access tokens for authorization need to validate the binding between the client and token. This document describes how to perform such validation, depending on which mechanism was used to produce a PoP token.
+IdentityServer can [bind tokens to clients](/identityserver/tokens/pop.md#proof-of-possession-styles) using either mTLS or
+DPoP, creating a `Proof-of-Possession` (PoP) access token. When one of these mechanisms is used, APIs that use those
+access tokens for authorization need to validate the binding between the client and token. This document describes how
+to perform such validation, depending on which mechanism was used to produce a PoP token.
 
 ### Validating mTLS
 
-If you are using a [mutual TLS connection](/identityserver/tokens/pop#mutual-tls) to establish proof-of-possession, the resulting access token will contain a `cnf` claim containing the client's certificate thumbprint. APIs validate such tokens by comparing this thumbprint to the thumbprint of the client certificate in the mTLS connection. This validation should be performed early in the pipeline, ideally immediately after the standard validation of the access token.
+If you are using a [mutual TLS connection](/identityserver/tokens/pop#mutual-tls) to establish proof-of-possession, the
+resulting access token will contain a `cnf` claim containing the client's certificate thumbprint. APIs validate such
+tokens by comparing this thumbprint to the thumbprint of the client certificate in the mTLS connection. This validation
+should be performed early in the pipeline, ideally immediately after the standard validation of the access token.
 
 You can do so with custom middleware like this:
 
@@ -28,7 +34,8 @@ app.UseConfirmationValidation();
 app.UseAuthorization();
 ```
 
-Here, `UseConfirmationValidation` is an extension method that registers the middleware that performs the necessary validation:
+Here, `UseConfirmationValidation` is an extension method that registers the middleware that performs the necessary
+validation:
 
 ```cs
 public static class ConfirmationValidationExtensions
@@ -109,11 +116,31 @@ public class ConfirmationValidationMiddlewareOptions
 ```
 
 ### Validating DPoP
-If you are using [DPoP](/identityserver/tokens/pop) for proof-of-possession, there is a non-trivial amount of work needed to validate the `cnf` claim.
-In addition to the normal validation mechanics of the access token itself, DPoP requires additional validation of the DPoP proof token sent in the "DPoP" HTTP request header.
-DPoP proof token processing involves requiring the DPoP scheme on the authorization header where the access token is sent, JWT validation of the proof token, "cnf" claim validation, HTTP method and URL validation, replay detection (which requires some storage for the replay information), nonce generation and validation, additional clock skew logic, and emitting the correct response headers in the case of the various validation errors.
 
-You can use the `Duende.AspNetCore.Authentication.JwtBearer` NuGet package to implement this validation. With this package, the configuration necessary in your startup can be as simple as this:
+When using [DPoP](/identityserver/tokens/pop#enabling-dpop-in-identityserver) for proof-of-possession, validating the `cnf` claim requires several
+steps:
+
+1. Validating the access token as normal
+2. Validating the DPoP proof token from the `DPoP` HTTP request header
+3. Ensuring the authorization header uses the DPoP scheme
+4. Validating the JWT format of the proof token
+5. Verifying the `cnf` claim matches between tokens
+6. Validating the HTTP method and URL match the request
+7. Detecting replay attacks using storage
+8. Managing nonce generation and validation
+9. Handling clock skew between systems
+10. Returning appropriate error response headers when validation fails
+
+This comprehensive validation process requires careful implementation to ensure security. Luckily for
+developers, we've implemented these steps into an easy-to-use library.
+
+You can use the `Duende.AspNetCore.Authentication.JwtBearer` NuGet package to implement this validation.
+
+```bash
+dotnet add package Duende.AspnetCore.Authentication.JwtBearer
+```
+
+With this package, the configuration necessary in your startup can be as simple as this:
 
 ```cs
 // adds the normal JWT bearer validation
@@ -132,8 +159,8 @@ builder.Services.ConfigureDPoPTokensForScheme("token");
 ```
 
 You will also typically need a distributed cache, used to perform replay detection of DPoP
-proofs. Duende.AspNetCore.Authentication.JwtBearer relies on `IDistributedCache` for this,
-so you can supply the cache implementation of your choice. See the 
+proofs. `Duende.AspNetCore.Authentication.JwtBearer` relies on `IDistributedCache` for this,
+so you can supply the cache implementation of your choice. See the
 [Microsoft documentation](https://learn.microsoft.com/en-us/aspnet/core/performance/caching/distributed?view=aspnetcore-8.0)
 for more details on setting up distributed caches, along with many examples, including Redis, CosmosDB, and
 Sql Server.

src/content/docs/identityserver/apis/aspnetcore/confirmation.md

@@ -29,7 +29,7 @@ Given that the access token has a finite lifetime, you typically want to
 
 ASP.NET Core has built-in facilities that can help you with some of those tasks
 (like caching or sessions), but there is still quite some work left to do.
-[Duende.AccessTokenManagement](https://github.com/DuendeSoftware/Duende.AccessTokenManagement/wiki)
+[Duende.AccessTokenManagement](/accesstokenmanagement)
 can help. It provides abstractions for storing tokens, automatic refresh of expired tokens, etc.
 
 ## Requesting A Refresh Token

src/content/docs/identityserver/quickstarts/3a-token-management.md

@@ -75,7 +75,7 @@ Key takeaways:
 ### MVC Client with automatic Access Token Management
 
 This sample shows how to
-use [Duende.AccessTokenManagement](https://github.com/DuendeSoftware/Duende.AccessTokenManagement/wiki) to automatically
+use [Duende.AccessTokenManagement](/accesstokenmanagement) to automatically
 manage access tokens.
 
 The sample uses a special client in the sample IdentityServer with a short token lifetime (75 seconds). When repeating

src/content/docs/identityserver/samples/basics.md

@@ -200,7 +200,7 @@ new Client
 #### Enabling DPoP Support In Your Client
 
 The easiest approach for supporting DPoP in your client is to use the DPoP support in the `Duende.AccessTokenManagement`
-library ([docs available here](https://github.com/DuendeSoftware/Duende.AccessTokenManagement/wiki/DPoP)).
+library ([docs available here](/accesstokenmanagement/advanced/dpop/)).
 It provides DPoP client support for both client credentials and code flow style clients.
 DPoP is enabled by assigning the `DPoPJsonWebKey` on the client configuration.
 

src/content/docs/identityserver/tokens/pop.md

@@ -63,7 +63,7 @@ var response = await client.RequestRefreshTokenAsync(new RefreshTokenRequest
 });
 ```
 
-The [Duende.AccessTokenManagement](https://github.com/DuendeSoftware/Duende.AccessTokenManagement/wiki) library can be
+The [Duende.AccessTokenManagement](/accesstokenmanagement) library can be
 used to automate refresh & access token lifetime management in ASP.NET Core.
 
 ## Binding Refresh Tokens

src/content/docs/identityserver/tokens/refresh.md

@@ -71,7 +71,7 @@ var response = await client.RequestClientCredentialsTokenAsync(new ClientCredent
 
 ### Automating Token Requests In ASP.NET Core And Worker Applications
 
-The [Duende.AccessTokenManagement](https://github.com/DuendeSoftware/Duende.AccessTokenManagement/wiki) library can automate client credential request and token lifetime management for you.
+The [Duende.AccessTokenManagement](/accesstokenmanagement) library can automate client credential request and token lifetime management for you.
 Using this library, you can enable access token management for an HTTP client provided by `IHttpClientFactory`.
 
 You can add the necessary services to ASP.NET Core's service provider by calling `AddClientCredentialsTokenManagement()`. One or more named client definitions need to be registered by calling `AddClient()`.
@@ -228,4 +228,4 @@ builder.Services.AddAuthentication(options =>
 ```
 
 ### Automating Token Management In ASP.NET Core
-The [Duende.AccessTokenManagement](https://github.com/DuendeSoftware/Duende.AccessTokenManagement/wiki) library can also be used to automate token lifetime management in ASP.NET Core applications for you.
+The [Duende.AccessTokenManagement](/accesstokenmanagement) library can also be used to automate token lifetime management in ASP.NET Core applications for you.