Merge pull request #712 from DuendeSoftware/wca/par-clarification

PAR guidance for .NET 9 and difference with .NET 8

Author: wcabus

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

@@ -21,7 +21,7 @@ Key takeaways:
 
 * how to request a token using client credentials
 * how to use a shared secret
-* how to use access token
+* how to use an access token
 
 [link to source code](https://github.com/DuendeSoftware/Samples/tree/main/IdentityServer/v7/Basics/ClientCredentials)
 
@@ -125,4 +125,13 @@ Key takeaways:
   would normally be sent in that redirect with the resulting request uri. See the `ParOidcEvents.cs` file for more
   details.
 
+:::note
+This sample is only relevant if you're using .NET 8 or lower.
+
+[.NET 9 has support for PAR built-in][ms-learn-par], and the ASP.NET Core OIDC authentication handler will automatically use 
+PAR when the authority supports it, based on the discovery metadata.  
+:::
+
 [link to source code](https://github.com/DuendeSoftware/Samples/tree/main/IdentityServer/v7/Basics/MvcPar)
+
+[ms-learn-par]: https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-9.0#openidconnecthandler-adds-support-for-pushed-authorization-requests-par

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

@@ -58,7 +58,27 @@ were just pushed. From there, the OAuth or OIDC flow continues as normal. For ex
 the user will be redirected to log in and other UI pages as necessary before being redirected back to the client with an
 authorization code which the client subsequently exchanges for tokens.
 
-A sample of how to implement this flow in an ASP.NET application is
+If you're building an ASP.NET Core application using .NET 9 or higher, using PAR is very straightforward:
+
+```csharp {13-15}
+// Program.cs
+builder.Services
+    .AddAuthentication(options =>
+    {
+        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
+        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
+    })
+    .AddCookie()
+    .AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, oidcOptions =>
+    {
+        // Your authority, client ID, ... configuration goes here.
+        
+        // By default, PushedAuthorizationBehavior is set to PushedAuthorizationBehavior.UseIfAvailable. 
+        // You can also require using PAR:
+        oidcOptions.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Require;
+    });
+```
+.NET 8 does not have built-in support for PAR. If you're using .NET 8, we have a sample of how to implement this flow
 available [here](/identityserver/samples/basics#mvc-client-with-pushed-authorization-requests).
 
 ## Data Store