Change how authentication demands are marshalled and support token binding certificates/additional token request parameters for interactive flows

Author: kevinchalet

sandbox/OpenIddict.Sandbox.Console.Client/InteractiveService.cs

@@ -44,6 +44,19 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken)
 
                 if (await AuthenticateUserInteractivelyAsync(registration, configuration, stoppingToken))
                 {
+                    // Note: the OpenIddict server stack supports mTLS-based token binding for public clients:
+                    // while these clients cannot authenticate using a TLS client certificate, the certificate
+                    // can be used to bind the refresh (and access) tokens returned by the authorization server
+                    // to the client application, which prevents such tokens from being used without providing a
+                    // proof-of-possession matching the TLS client certificate used when the token was acquired.
+                    //
+                    // While this sample deliberately doesn't store the generated certificate in a persistent
+                    // location, the certificate used for token binding should typically be stored in the user
+                    // certificate store to be reloaded across application restarts in a real-world application.
+                    var certificate = configuration.TlsClientCertificateBoundAccessTokens is true
+                        ? GenerateEphemeralTlsClientCertificate()
+                        : null;
+
                     var flow = await GetSelectedFlowAsync(registration, configuration, stoppingToken);
 
                     AnsiConsole.MarkupLine("[cyan]Launching the system browser.[/]");
@@ -64,7 +77,8 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken)
                     var response = await _service.AuthenticateInteractivelyAsync(new()
                     {
                         CancellationToken = stoppingToken,
-                        Nonce = result.Nonce
+                        Nonce = result.Nonce,
+                        TokenBindingCertificate = certificate
                     });
 
                     AnsiConsole.MarkupLine("[green]Interactive authentication successful:[/]");
@@ -112,7 +126,8 @@ await _service.RevokeTokenAsync(new()
                         {
                             CancellationToken = stoppingToken,
                             ProviderName = provider,
-                            RefreshToken = response.RefreshToken
+                            RefreshToken = response.RefreshToken,
+                            TokenBindingCertificate = certificate
                         })).Principal));
                     }
 
@@ -151,15 +166,6 @@ await _service.AuthenticateInteractivelyAsync(new()
                     var type = await GetSelectedGrantTypeAsync(registration, configuration, stoppingToken);
                     if (type is GrantTypes.DeviceCode)
                     {
-                        // Note: the OpenIddict server stack supports mTLS-based token binding for public clients:
-                        // while these clients cannot authenticate using a TLS client certificate, the certificate
-                        // can be used to bind the refresh (and access) tokens returned by the authorization server
-                        // to the client application, which prevents such tokens from being used without providing a
-                        // proof-of-possession matching the TLS client certificate used when the token was acquired.
-                        //
-                        // While this sample deliberately doesn't store the generated certificate in a persistent
-                        // location, the certificate used for token binding should typically be stored in the user
-                        // certificate store to be reloaded across application restarts in a real-world application.
                         var certificate = configuration.TlsClientCertificateBoundAccessTokens is true
                             ? GenerateEphemeralTlsClientCertificate()
                             : null;

src/OpenIddict.Client.SystemIntegration/OpenIddictClientSystemIntegrationHandlers.cs

@@ -833,8 +833,9 @@ public ValueTask HandleAsync(ProcessAuthenticationContext context)
                 ProviderTypes.PayPal => (false, false, false),
 
                 // NetSuite does not return an id_token when using the refresh_token grant type.
-                // Additionally, the at_hash inside their id_token is not a valid hash of the
-                // access token, but is instead a copy of the RS256 signature within the access token.
+                //
+                // Additionally, the at_hash inside the id_token is not a valid hash of the access
+                // token, but is instead a copy of the RS256 signature within the access token.
                 ProviderTypes.NetSuite => (true, false, false),
 
                 _ => (context.ExtractBackchannelIdentityToken,

src/OpenIddict.Client.WebIntegration/OpenIddictClientWebIntegrationHandlers.cs

@@ -441,6 +441,12 @@ public OpenIddictRequest Request
         [Obsolete("This property is no longer used and will be removed in a future version.")]
         public HashSet<string> UserInfoEndpointTokenBindingMethods { get; } = new(StringComparer.Ordinal);
 
+        /// <summary>
+        /// Gets or sets a boolean indicating whether the token entry associated
+        /// with the state token should be marked as redeemed in the database.
+        /// </summary>
+        public bool DisableStateTokenRedeeming { get; set; }
+
         /// <summary>
         /// Gets or sets a boolean indicating whether a token request should be sent.
         /// </summary>

src/OpenIddict.Client/OpenIddictClientEvents.cs

@@ -60,6 +60,7 @@ public static OpenIddictClientBuilder AddClient(this OpenIddictBuilder builder)
         builder.Services.TryAddSingleton<RequireRevocationClientAssertionGenerated>();
         builder.Services.TryAddSingleton<RequireRevocationRequest>();
         builder.Services.TryAddSingleton<RequireStateTokenPrincipal>();
+        builder.Services.TryAddSingleton<RequireStateTokenRedeemed>();
         builder.Services.TryAddSingleton<RequireStateTokenValidated>();
         builder.Services.TryAddSingleton<RequireTokenAudienceValidationEnabled>();
         builder.Services.TryAddSingleton<RequireTokenEntryCreated>();

src/OpenIddict.Client/OpenIddictClientExtensions.cs

@@ -406,6 +406,20 @@ public ValueTask<bool> IsActiveAsync(ProcessAuthenticationContext context)
         }
     }
 
+    /// <summary>
+    /// Represents a filter that excludes the associated handlers if the state token should not be redeemed.
+    /// </summary>
+    public sealed class RequireStateTokenRedeemed : IOpenIddictClientHandlerFilter<ProcessAuthenticationContext>
+    {
+        /// <inheritdoc/>
+        public ValueTask<bool> IsActiveAsync(ProcessAuthenticationContext context)
+        {
+            ArgumentNullException.ThrowIfNull(context);
+
+            return new(!context.DisableStateTokenRedeeming);
+        }
+    }
+
     /// <summary>
     /// Represents a filter that excludes the associated handlers if no state token is validated.
     /// </summary>

src/OpenIddict.Client/OpenIddictClientHandlerFilters.cs

@@ -824,6 +824,7 @@ public RedeemStateTokenEntry(IOpenIddictTokenManager tokenManager)
             = OpenIddictClientHandlerDescriptor.CreateBuilder<ProcessAuthenticationContext>()
                 .AddFilter<RequireTokenStorageEnabled>()
                 .AddFilter<RequireStateTokenPrincipal>()
+                .AddFilter<RequireStateTokenRedeemed>()
                 .AddFilter<RequireStateTokenValidated>()
                 .UseScopedHandler<RedeemStateTokenEntry>()
                 // Note: this handler is deliberately executed early in the pipeline to ensure that
@@ -896,7 +897,7 @@ public ValueTask HandleAsync(ProcessAuthenticationContext context)
             // Reject the authentication demand if the expected endpoint type doesn't
             // match the current endpoint type as it may indicate a mix-up attack (e.g a
             // state token created for a logout operation was used for a login operation).
-            if (type != context.EndpointType)
+            if (context.EndpointType is not OpenIddictClientEndpointType.Unknown && context.EndpointType != type)
             {
                 context.Reject(
                     error: Errors.InvalidRequest,
@@ -995,6 +996,12 @@ public ValueTask HandleAsync(ProcessAuthenticationContext context)
 
             Debug.Assert(context.StateTokenPrincipal is { Identity: ClaimsIdentity }, SR.GetResourceString(SR.ID4006));
 
+            // Only validate the endpoint type if the endpoint is well-known.
+            if (context.EndpointType is OpenIddictClientEndpointType.Unknown)
+            {
+                return ValueTask.CompletedTask;
+            }
+
             // Resolve the endpoint type allowed to be used with the state token.
             if (!Enum.TryParse(context.StateTokenPrincipal.GetClaim(Claims.Private.EndpointType),
                 ignoreCase: true, out OpenIddictClientEndpointType type))
@@ -1174,8 +1181,8 @@ public ValueTask HandleAsync(ProcessAuthenticationContext context)
         {
             ArgumentNullException.ThrowIfNull(context);
 
-            // To help mitigate mix-up attacks, the identity of the issuer can be returned by
-            // authorization servers that support it as a part of the "iss" parameter, which
+            // To help mitigate mix-up attacks, the identity of the issuer can be returned
+            // by authorization servers that support it as part of the "iss" parameter, which
             // allows comparing it to the issuer in the state token. Depending on the selected
             // response_type, the same information could be retrieved from the identity token
             // that is expected to contain an "iss" claim containing the issuer identity.
@@ -1217,6 +1224,7 @@ public ValueTask HandleAsync(ProcessAuthenticationContext context)
 
             // Reject authorization responses containing an "iss" parameter if the configuration
             // doesn't indicate this parameter is supported, as recommended by the specification.
+            //
             // See https://datatracker.ietf.org/doc/html/draft-ietf-oauth-iss-auth-resp-05#section-2.4
             // for more information.
             else if (!string.IsNullOrEmpty(issuer))
@@ -1467,7 +1475,7 @@ GrantTypes.AuthorizationCode or GrantTypes.Implicit when
     }
 
     /// <summary>
-    /// Contains the logic responsible for resolving the token from the incoming request.
+    /// Contains the logic responsible for resolving the frontchannel tokens from the incoming request.
     /// </summary>
     public sealed class ResolveValidatedFrontchannelTokens : IOpenIddictClientHandler<ProcessAuthenticationContext>
     {

src/OpenIddict.Client/OpenIddictClientHandlers.cs

@@ -20,6 +20,11 @@ public static class OpenIddictClientModels
     /// </summary>
     public sealed record class InteractiveAuthenticationRequest
     {
+        /// <summary>
+        /// Gets or sets the parameters that will be added to the token request, if applicable.
+        /// </summary>
+        public Dictionary<string, OpenIddictParameter>? AdditionalTokenRequestParameters { get; init; }
+
         /// <summary>
         /// Gets or sets the cancellation token that will be
         /// used to determine if the operation was aborted.
@@ -35,6 +40,23 @@ public sealed record class InteractiveAuthenticationRequest
         /// Gets or sets the application-specific properties that will be added to the context.
         /// </summary>
         public Dictionary<string, string?>? Properties { get; init; }
+
+        /// <summary>
+        /// Gets or sets the X.509 client certificate used to bind the access and/or
+        /// refresh tokens issued by the authorization server, if applicable.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Note: when mTLs is also used for OAuth 2.0 client authentication, the
+        /// certificate set here replaces the client certificate chosen by OpenIddict.
+        /// </para>
+        /// <para>
+        /// Note: if a certificate-based client authentication or token binding method is
+        /// negotiated, the type of the certificate must match the negotiated methods.
+        /// </para>
+        /// </remarks>
+        [EditorBrowsable(EditorBrowsableState.Advanced)]
+        public X509Certificate2? TokenBindingCertificate { get; init; }
     }
 
     /// <summary>

src/OpenIddict.Client/OpenIddictClientModels.cs

@@ -271,7 +271,10 @@ public async ValueTask<InteractiveAuthenticationResult> AuthenticateInteractivel
         var context = new ProcessAuthenticationContext(transaction)
         {
             CancellationToken = request.CancellationToken,
-            Nonce = request.Nonce
+            Nonce = request.Nonce,
+            TokenEndpointClientCertificate = request.TokenBindingCertificate,
+            TokenRequest = request.AdditionalTokenRequestParameters
+                is Dictionary<string, OpenIddictParameter> parameters ? new(parameters) : new()
         };
 
         if (request.Properties is { Count: > 0 })