Merge pull request #611 from DuendeSoftware/mb/experimental

Add docs about preview/experimental features

Author: maartenba

FOSS/content/AccessTokenManagement/Advanced/client_assertions.md

@@ -40,6 +40,11 @@ public class ClientAssertionService : IClientAssertionService
                     { JwtClaimTypes.JwtId, Guid.NewGuid().ToString() },
                     { JwtClaimTypes.Subject, options.ClientId! },
                     { JwtClaimTypes.IssuedAt, DateTime.UtcNow.ToEpochTime() }
+                },
+
+                AdditionalHeaderClaims = new Dictionary<string, object>
+                {
+                    { JwtClaimTypes.TokenType, "client-authentication+jwt" }
                 }
             };
 

IdentityServer/v7/docs/content/reference/options.md

@@ -723,3 +723,36 @@ Demonstration of Proof-of-Possession settings. Available on the *DPoP* property
 * ***Lifetime***
 
     Controls the lifetime of pushed authorization requests. The pushed authorization request's lifetime begins when the request to the PAR endpoint is received, and is validated until the authorize endpoint returns a response to the client application. Note that user interaction, such as entering credentials or granting consent, may need to occur before the authorize endpoint can do so. Setting the lifetime too low will likely cause login failures for interactive users, if pushed authorization requests expire before those users complete authentication. Some security profiles, such as the FAPI 2.0 Security Profile recommend an expiration within 10 minutes to prevent attackers from pre-generating requests. To balance these constraints, this lifetime defaults to 10 minutes. 
+
+## Preview Features
+Preview Features settings. Available on the *Preview* property of the *IdentityServerOptions* object.
+
+{{% notice 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.
+{{% /notice %}}
+
+#### Discovery Document Cache
+
+In large deployments of Duende IdentityServer, where a lot of concurrent users attempt to
+consume the [discovery endpoint]({{< ref "reference/endpoints/discovery" >}}) 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*]({{< ref "/tokens/authentication/jwt" >}}),
+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]({{< ref "/tokens/authentication/jwt#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.

IdentityServer/v7/docs/content/tokens/authentication/jwt.md

@@ -165,3 +165,27 @@ public class OidcEvents : OpenIdConnectEvents
 
 The assertion service would be a helper to create the JWT as shown above in the *CreateClientToken* method.
 See [here]({{< ref "/samples/basics#mvc-client-with-jar-and-jwt-based-authentication" >}}) for a sample for using JWT-based authentication (and signed authorize requests) in ASP.NET Core.
+
+## Strict Audience Validation
+
+Private key JWT have 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 attack relies on the OpenID Provider setting the audience value of the authentication JWT
+to the token endpoint based on the token endpoint value found in the discovery document.
+The malicious Open ID Provider can attack this because it controls what the discovery document
+contains, and can fool the Relying Party into creating authentication JWTs for the audience of
+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**]({{< ref "/reference/options/#strict-audience-validation" >}})
+flag, which strictly validates that the audience is equal to the issuer and validates the token's
+`typ` header.
+
+Validation behavior is determined based on the `typ` header being present.
+If the **StrictClientAssertionAudienceValidation** flag is not set but the token sets the `typ`
+to `client-authentication+jwt`, then the audience will still be validated strictly.
+If `typ` is not present, [default audience validation]({{< ref "/apis/aspnetcore/jwt/#adding-audience-validation" >}})
+is used.