Validate mTLS Bound Tokens

What you'll cover

• Configure Kestrel to request a client certificate
• Enable certificate binding validation

Before you begin

This guide assumes you've completed the installation guide.

You should already have:

• An ASP.NET Core project
• The MonoCloud.Authentication.Api SDK installed
• The MonoCloud section configured in appsettings.json

Configure the server

Configure Kestrel to request client certificates during the TLS handshake, then enable certificate binding validation.

using MonoCloud.Authentication.Api;
using Microsoft.AspNetCore.Server.Kestrel.Https;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(kestrel =>
{
    kestrel.ConfigureHttpsDefaults(https =>
    {
        https.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
        https.ClientCertificateValidation = (_, _, _) => true;
    });
});

builder.Services
    .AddAuthentication(MonoCloudAuthenticationDefaults.AuthenticationScheme)
    .AddMonoCloudAuthentication(options =>
    {
        options.TenantDomain = builder.Configuration["MonoCloud:TenantDomain"];
        options.Audience = builder.Configuration["MonoCloud:Audience"];

        options.ValidateCertificateBinding = _ => true;
    });

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/api/data", () => "Protected data")
   .RequireAuthorization();

app.Run();

How it works:

• ClientCertificateMode.AllowCertificate tells Kestrel to request a client certificate during the TLS handshake
• ClientCertificateValidation returns true so the application handles binding validation instead of rejecting the request at the TLS layer
• ValidateCertificateBinding = _ => true verifies that the token's cnf.x5t#S256 claim matches the SHA-256 thumbprint of the presented client certificate
• The client certificate is read from the HTTP connection object

Response behavior

Next steps

• Protect API routes
• Introspect Access Tokens
• Use multiple schemes
• Add a custom cache