Revamp the client authentication method negotiation logic and support mTLS token binding in the client, server and validation stacks

Author: kevinchalet

gen/OpenIddict.Client.WebIntegration.Generators/OpenIddictClientWebIntegrationGenerator.cs

@@ -285,6 +285,18 @@ public sealed partial class {{ provider.name }}
             return Set(registration => registration.ClientSecret = secret);
         }
 
+        /// <summary>
+        /// Sets the client type (typically, ""public"" or ""confidential"").
+        /// </summary>
+        /// <param name=""type"">The client type.</param>
+        /// <returns>The <see cref=""OpenIddictClientWebIntegrationBuilder.{{ provider.name }}""/> instance.</returns>
+        public {{ provider.name }} SetClientType(string type)
+        {
+            ArgumentException.ThrowIfNullOrEmpty(type);
+
+            return Set(registration => registration.ClientType = type);
+        }
+
         /// <summary>
         /// Sets the post-logout redirection URI, if applicable.
         /// </summary>

sandbox/OpenIddict.Sandbox.AspNetCore.Client/Controllers/HomeController.cs

@@ -39,9 +39,9 @@ public async Task<ActionResult> GetMessage(CancellationToken cancellationToken)
         // authentication options shouldn't be used, a specific scheme can be specified here.
         var token = await HttpContext.GetTokenAsync(Tokens.BackchannelAccessToken);
 
-        using var client = _httpClientFactory.CreateClient();
+        using var client = _httpClientFactory.CreateClient("ApiClient");
 
-        using var request = new HttpRequestMessage(HttpMethod.Get, "https://localhost:44395/api/message");
+        using var request = new HttpRequestMessage(HttpMethod.Get, "api/message");
         request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
 
         using var response = await client.SendAsync(request, cancellationToken);

sandbox/OpenIddict.Sandbox.AspNetCore.Client/Startup.cs

@@ -168,7 +168,7 @@ public void ConfigureServices(IServiceCollection services)
                 // to authenticate using either PKI certificates or self-signed certificates.
                 //
                 // Note: PKI and self-signed certificate authentication can be enabled independently.
-                options.EnablePublicKeyInfrastructureClientCertificateAuthentication(
+                options.EnablePublicKeyInfrastructureTlsClientAuthentication(
                 [
                     // Root certificate:
                     X509Certificate2.CreateFromPem($"""
@@ -239,12 +239,11 @@ public void ConfigureServices(IServiceCollection services)
                         """)
                 ]);
 
-                options.EnableSelfSignedClientCertificateAuthentication();
+                options.EnableSelfSignedTlsClientAuthentication();
 
-                // Note: setting a static issuer is mandatory when using mTLS aliases
-                // to ensure it is not dynamically computed based on the request URI,
-                // as this would result in two different issuers being used (one
-                // pointing to the mTLS domain and one pointing to the regular one).
+                // Note: setting a static issuer is mandatory when using mTLS aliases to ensure it not
+                // dynamically computed based on the request URI, as this would result in two different
+                // issuers being used (one pointing to the mTLS domain and one pointing to the regular one).
                 options.SetIssuer("https://localhost:44395/");
 
                 // Configure the mTLS endpoint aliases that will be used by client applications opting
@@ -260,7 +259,20 @@ public void ConfigureServices(IServiceCollection services)
                        .SetMtlsIntrospectionEndpointAliasUri("https://mtls.dev.localhost:44395/connect/introspect")
                        .SetMtlsPushedAuthorizationEndpointAliasUri("https://mtls.dev.localhost:44395/connect/par")
                        .SetMtlsRevocationEndpointAliasUri("https://mtls.dev.localhost:44395/connect/revoke")
-                       .SetMtlsTokenEndpointAliasUri("https://mtls.dev.localhost:44395/connect/token");
+                       .SetMtlsTokenEndpointAliasUri("https://mtls.dev.localhost:44395/connect/token")
+                       .SetMtlsUserInfoEndpointAliasUri("https://mtls.dev.localhost:44395/connect/userinfo");
+
+                // While public client applications cannot use mTLS for client authentication, they can use
+                // mTLS purely as a token binding mechanism: in this case, the refresh tokens issued to
+                // public clients sending a client certificate are automatically bound to the certificate,
+                // which requires sending the same certificate when using them to get new access tokens.
+                options.UseClientCertificateBoundRefreshTokens();
+
+                // Optionally, the server stack can be configured to issue client certificate-bound access tokens.
+                //
+                // When doing so, the standard "cnf" claim is automatically added to access tokens to inform
+                // resource servers that a proof of possession derived from the certificate must be provided.
+                options.UseClientCertificateBoundAccessTokens();
 #endif
             })
 

sandbox/OpenIddict.Sandbox.AspNetCore.Server/Startup.cs

@@ -1,4 +1,7 @@
-using System.Security.Claims;
+using System.Runtime.InteropServices;
+using System.Security.Claims;
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
 using Microsoft.Extensions.Hosting;
 using OpenIddict.Abstractions;
 using OpenIddict.Client;
@@ -148,6 +151,19 @@ 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;
+
                         // Ask OpenIddict to send a device authorization request and write
                         // the complete verification endpoint URI to the console output.
                         var result = await _service.ChallengeUsingDeviceAsync(new()
@@ -181,7 +197,8 @@ [yellow]Please visit [link]{result.VerificationUri}[/] and enter
                             DeviceCode = result.DeviceCode,
                             Interval = result.Interval,
                             ProviderName = provider,
-                            Timeout = result.ExpiresIn < TimeSpan.FromMinutes(5) ? result.ExpiresIn : TimeSpan.FromMinutes(5)
+                            Timeout = result.ExpiresIn < TimeSpan.FromMinutes(5) ? result.ExpiresIn : TimeSpan.FromMinutes(5),
+                            TokenBindingCertificate = certificate
                         });
 
                         AnsiConsole.MarkupLine("[green]Device authentication successful:[/]");
@@ -223,7 +240,8 @@ await _service.RevokeTokenAsync(new()
                             {
                                 CancellationToken = stoppingToken,
                                 ProviderName = provider,
-                                RefreshToken = response.RefreshToken
+                                RefreshToken = response.RefreshToken,
+                                TokenBindingCertificate = certificate
                             })).Principal));
                         }
                     }
@@ -232,6 +250,10 @@ await _service.RevokeTokenAsync(new()
                     {
                         var (username, password) = (await GetUsernameAsync(stoppingToken), await GetPasswordAsync(stoppingToken));
 
+                        var certificate = configuration.TlsClientCertificateBoundAccessTokens is true
+                            ? GenerateEphemeralTlsClientCertificate()
+                            : null;
+
                         AnsiConsole.MarkupLine("[cyan]Sending the token request.[/]");
 
                         // Ask OpenIddict to authenticate the user using the resource owner password credentials grant.
@@ -241,7 +263,8 @@ await _service.RevokeTokenAsync(new()
                             ProviderName = provider,
                             Username = username,
                             Password = password,
-                            Scopes = [Scopes.OfflineAccess]
+                            Scopes = [Scopes.OfflineAccess],
+                            TokenBindingCertificate = certificate
                         });
 
                         AnsiConsole.MarkupLine("[green]Resource owner password credentials authentication successful:[/]");
@@ -283,7 +306,8 @@ await _service.RevokeTokenAsync(new()
                             {
                                 CancellationToken = stoppingToken,
                                 ProviderName = provider,
-                                RefreshToken = response.RefreshToken
+                                RefreshToken = response.RefreshToken,
+                                TokenBindingCertificate = certificate
                             })).Principal));
                         }
                     }
@@ -309,6 +333,10 @@ await GetRequestedTokenTypeAsync(stoppingToken),
                             await GetSubjectTokenAsync(stoppingToken),
                             await GetActorTokenAsync(stoppingToken));
 
+                        var certificate = configuration.TlsClientCertificateBoundAccessTokens is true
+                            ? GenerateEphemeralTlsClientCertificate()
+                            : null;
+
                         AnsiConsole.MarkupLine("[cyan]Sending the token request.[/]");
 
                         // Ask OpenIddict to send the specified subject token (and actor token, if available).
@@ -320,7 +348,8 @@ await GetSubjectTokenAsync(stoppingToken),
                             ProviderName = provider,
                             RequestedTokenType = identifier,
                             SubjectToken = subject.Token,
-                            SubjectTokenType = subject.TokenType
+                            SubjectTokenType = subject.TokenType,
+                            TokenBindingCertificate = certificate
                         });
 
                         AnsiConsole.MarkupLine("[green]Token exchange authentication successful:[/]");
@@ -368,7 +397,8 @@ await RefreshTokenAsync(stoppingToken))
                             {
                                 CancellationToken = stoppingToken,
                                 ProviderName = provider,
-                                RefreshToken = response.IssuedToken
+                                RefreshToken = response.IssuedToken,
+                                TokenBindingCertificate = certificate
                             })).Principal));
                         }
 
@@ -381,7 +411,8 @@ await RefreshTokenAsync(stoppingToken))
                             {
                                 CancellationToken = stoppingToken,
                                 ProviderName = provider,
-                                RefreshToken = response.RefreshToken
+                                RefreshToken = response.RefreshToken,
+                                TokenBindingCertificate = certificate
                             })).Principal));
                         }
                     }
@@ -800,5 +831,44 @@ static bool Prompt() => AnsiConsole.Prompt(new ConfirmationPrompt(
 
             return Task.Run(Prompt, cancellationToken).WaitAsync(cancellationToken);
         }
+
+#if SUPPORTS_CERTIFICATE_GENERATION
+        static X509Certificate2 GenerateEphemeralTlsClientCertificate()
+        {
+            using var algorithm = RSA.Create(keySizeInBits: 4096);
+
+            var subject = new X500DistinguishedName("CN=Self-signed certificate");
+            var request = new CertificateRequest(subject, algorithm, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
+            request.CertificateExtensions.Add(new X509KeyUsageExtension(X509KeyUsageFlags.DigitalSignature, critical: true));
+            request.CertificateExtensions.Add(new X509EnhancedKeyUsageExtension([new Oid("1.3.6.1.5.5.7.3.2")], critical: true));
+
+            var certificate = request.CreateSelfSigned(DateTimeOffset.UtcNow, DateTimeOffset.UtcNow.AddYears(2));
+
+            // On Windows, a certificate loaded from PEM-encoded material is ephemeral and
+            // cannot be directly used with TLS, as Schannel cannot access it in this case.
+            //
+            // To work this limitation, the certificate is exported and re-imported from a
+            // PFX blob to ensure the private key is persisted in a way that Schannel can use.
+            //
+            // In a real world application, the certificate wouldn't be embedded in the source code
+            // and would be installed in the certificate store, making this workaround unnecessary.
+            if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+            {
+#if SUPPORTS_CERTIFICATE_LOADER
+                certificate = X509CertificateLoader.LoadPkcs12(
+                    data: certificate.Export(X509ContentType.Pfx, string.Empty),
+                    password: string.Empty,
+                    keyStorageFlags: X509KeyStorageFlags.DefaultKeySet);
+#else
+                certificate = new X509Certificate2(
+                    rawData: certificate.Export(X509ContentType.Pfx, string.Empty),
+                    password: string.Empty,
+                    keyStorageFlags: X509KeyStorageFlags.DefaultKeySet);
+#endif
+            }
+
+            return certificate;
+        }
+#endif
     }
 }

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

@@ -1104,6 +1104,22 @@ public static bool IsSelfIssuedCertificate(X509Certificate2 certificate)
         return certificate.SubjectName.RawData.AsSpan().SequenceEqual(certificate.IssuerName.RawData);
     }
 
+    /// <summary>
+    /// Determines whether the specified <paramref name="certificate"/> is suitable for client authentication.
+    /// </summary>
+    /// <param name="certificate">The <see cref="X509Certificate2"/>.</param>
+    /// <returns>
+    /// <see langword="true"/> if the certificate is suitable for client authentication, <see langword="false"/> otherwise.
+    /// </returns>
+    public static bool IsClientAuthenticationCertificate(X509Certificate2 certificate)
+    {
+        ArgumentNullException.ThrowIfNull(certificate);
+
+        return certificate.Version is >= 3 &&
+            OpenIddictHelpers.HasKeyUsage(certificate, X509KeyUsageFlags.DigitalSignature) &&
+            OpenIddictHelpers.HasExtendedKeyUsage(certificate, ObjectIdentifiers.ExtendedKeyUsages.ClientAuthentication);
+    }
+
     /// <summary>
     /// Determines whether the items contained in <paramref name="element"/>
     /// are of the specified <paramref name="kind"/>.

shared/OpenIddict.Extensions/OpenIddictHelpers.cs

@@ -8,7 +8,6 @@
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using System.Runtime.Versioning;
-using System.Security.Cryptography;
 using System.Security.Cryptography.X509Certificates;
 
 namespace OpenIddict.Extensions;