AspNet.KeyCloak.DPoP 1.0.3

A library that provides everything the standard JWT Bearer authentication offers, with the added power of built-in DPoP (Demonstration of Proof-of-Possession) support for enhanced token security. Simplify your KeyCloak JWT authentication integration for ASP.NET Core APIs with KeyCloak-specific configuration and validation.

Table of Contents

• Features
• Requirements
• Installation
• Migration from JWT Bearer
• Getting Started
  • Basic Configuration
  • Configuration Options
• DPoP: Enhanced Token Security
  • Enabling DPoP
  • DPoP Configuration Options
  • DPoP Modes
• Advanced Features
  • Using Full JWT Bearer Options
• Examples
• Development
  • Building the Project
  • Running Tests
  • Playground Application
• Contributing
• Support
• License

Features

This library builds on top of the standard Microsoft.AspNetCore.Authentication.JwtBearer package, providing:

• Complete JWT Bearer Functionality - All features from Microsoft.AspNetCore.Authentication.JwtBearer are available
• Built-in DPoP Support - Industry-leading proof-of-possession token security per RFC 9449
• KeyCloak Optimized - Pre-configured for KeyCloak's authentication patterns
• Zero Lock-in - Use standard JWT Bearer features alongside DPoP enhancements
• Single Package – Everything you need in one dependency
• Flexible Configuration – Options pattern with full access to underlying JWT Bearer configuration

Requirements

• This library currently supports .NET 10.0 and above.

Installation

Install the package via NuGet Package Manager:

dotnet add package AspNet.KeyCloak.DPoP

Or via the Package Manager Console:

Install-Package AspNet.KeyCloak.DPoP

Migration from JWT Bearer

Already using Microsoft.AspNetCore.Authentication.JwtBearer? Great news! This library is a drop-in replacement with zero behavior changes.

Quick Migration

Migrating from JWT Bearer is simple:

Before:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = $"https://{builder.Configuration["KeyCloak:Domain"]}";
        options.Audience = builder.Configuration["KeyCloak:Audience"];
    });

After:

builder.Services.AddKeyCloakApiAuthentication(options =>
{
    options.Domain = builder.Configuration["KeyCloak:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["KeyCloak:Audience"]
    };
});

What You Get

Zero Breaking Changes – All JWT Bearer functionality works identically 5–15 Lines – Typically only 5–15 lines of code change
Full Compatibility – Custom events, validation, and policies work as-is
New Capabilities – Optional DPoP support with zero refactoring

Getting Started

Basic Configuration

Add KeyCloak authentication to your ASP.NET Core API in Program.cs:

using AspNet.KeyCloak.DPoP;

using Microsoft.AspNetCore.Authentication.JwtBearer;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Adds KeyCloak JWT validation to the API
builder.Services.AddKeyCloakApiAuthentication(options =>
{
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["KeyCloak:Audience"]
    };
});

builder.Services.AddAuthorization();

WebApplication app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

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

app.MapGet("/open-endpoint", () =>
    {
        var responseMessage = "This endpoint is available to all users.";
        return responseMessage;
    })
    .WithName("AccessOpenEndpoint")
    .WithOpenApi();

app.MapGet("/restricted-endpoint", () =>
    {
        var responseMessage = "This endpoint is available only to authenticated users.";
        return responseMessage;
    })
    .WithName("AccessRestrictedEndpoint")
    .WithOpenApi().RequireAuthorization();

app.Run();

Want more examples? Check out EXAMPLES.md for comprehensive code examples including authorization policies, scopes, permissions, custom handlers, and more!

Configuration Options

Add the following settings to your appsettings.json:

{
  "KeyCloak": {
    "Domain": "your-tenant.example.com/realms/your-realm/",
    "Audience": "your-api-identifier"
  }
}

Required Settings:

• Domain: Your KeyCloak domain including realm path (e.g., my-host.example.com/realms/my-realm/) - without the https:// prefix
• Audience: The audience identifier for your API configured in KeyCloak

The library automatically constructs the authority URL as https://{Domain}.

For local development (where KeyCloak may run on HTTP), use the Authority option to override:

options.Authority = "http://localhost:8080/realms/my-realm";

When Authority is set it takes precedence over Domain.

DPoP: Enhanced Token Security

DPoP (Demonstration of Proof-of-Possession) is a security mechanism that binds access tokens to a cryptographic key, making them resistant to token theft and replay attacks. This library provides seamless DPoP integration for your KeyCloak-protected APIs.

Learn more about DPoP: RFC 9449 - OAuth 2.0 Demonstrating Proof of Possession

Enabling DPoP

Enable DPoP with a single method call:

builder.Services.AddKeyCloakApiAuthentication(options =>
{
    options.Domain = builder.Configuration["KeyCloak:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["KeyCloak:Audience"]
    };
}).WithDPoP(); // Enable DPoP support

That's it! Your API now supports DPoP tokens while maintaining backward compatibility with Bearer tokens.

DPoP Configuration Options

For fine-grained control, configure DPoP behavior:

builder.Services.AddKeyCloakApiAuthentication(options =>
{
    options.Domain = builder.Configuration["KeyCloak:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["KeyCloak:Audience"]
    };
}).WithDPoP(dpopOptions =>
{
    // Enforcement mode
    dpopOptions.Mode = DPoPModes.Required;
    
    // Time validation settings
    dpopOptions.IatOffset = 300; // Allow 300 seconds offset for 'iat' claim (default)
    dpopOptions.Leeway = 30;     // 30 seconds leeway for time-based validation (default)
});

DPoP Modes

Choose the right enforcement mode for your security requirements:

Advanced Features

Using Full JWT Bearer Options

Since this library provides complete access to JWT Bearer configuration, you can use any standard JWT Bearer option:

builder.Services.AddKeyCloakApiAuthentication(options =>
{
    options.Domain = builder.Configuration["KeyCloak:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["KeyCloak:Audience"],
        
        // All standard JWT Bearer options are available
        RequireHttpsMetadata = true,
        SaveToken = true,
        IncludeErrorDetails = true,
        
        // Custom token validation parameters
        TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuerSigningKey = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromMinutes(5),
            NameClaimType = ClaimTypes.NameIdentifier
        },
        
        // Event handlers for custom logic
        Events = new JwtBearerEvents
        {
            OnAuthenticationFailed = context =>
            {
                Console.WriteLine($"Authentication failed: {context.Exception.Message}");
                return Task.CompletedTask;
            }
        }
    };
});

Looking for more advanced scenarios? Visit EXAMPLES.md for examples on:

• Scope and permission-based authorization
• Custom authorization handlers
• Role-based access control
• Custom JWT Bearer events
• SignalR integration
• Error handling and logging
• And much more!

Examples

For comprehensive, copy-pastable code examples covering various scenarios, see EXAMPLES.md:

• Getting Started – Basic authentication and endpoint protection
• Configuration – Custom token validation and settings
• DPoP – All DPoP modes with practical examples
• Authorization – Scopes, permissions, roles, and custom handlers
• Advanced Scenarios – Claims, events, custom error responses
• Integration – SignalR and other integrations

Development

Building the Project

Clone the repository and build the solution:

git clone https://github.com/ChrisMcKee/aspnet-jwt-dpop.git
cd aspnet-jwt-dpop
dotnet restore AspNet.KeyCloak.DPoP.sln
dotnet build AspNet.KeyCloak.DPoP.sln --configuration Release

Running Tests

Run the unit test suite (no external dependencies):

dotnet test tests/UnitTests/

Integration tests require a running KeyCloak instance (use the Aspire playground):

dotnet test tests/IntegrationTests/

Playground Application

The repository includes a full playground using .NET Aspire to orchestrate all components. No manual KeyCloak setup required — the realm is imported automatically.

Setup

Prerequisites: .NET 10 SDK and Docker (for Keycloak)

1. Run the Aspire AppHost:

   cd AppHost
   dotnet run
   

2. Access the components:

   • Aspire Dashboard: https://localhost:17216
   • Frontend (Vite/React OIDC client): https://localhost:3000
   • Backend API (Swagger): https://localhost:3445/swagger
   • Keycloak admin: https://localhost:3443

The test realm is pre-configured with a frontend-client (public OIDC client with DPoP) and a rwo-backend API audience.

See the Playground Server README for endpoint details and manual testing instructions.

Contributing

Contributions are welcome! Please ensure all tests pass and add tests for new functionality.

Contribution Checklist

• ✅ Ensure all unit tests pass: dotnet test tests/UnitTests/
• ✅ Add tests for new functionality
• ✅ Update documentation as needed

Support

If you have questions or need help:

• 📖 See EXAMPLES.md for code examples
• 🐛 Report issues on GitHub Issues

License

Copyright 2026 Chris McKee Copyright 2025 Okta, Inc.

This project is licensed under the Apache License 2.0 – see the LICENSE file for details.

Authors: Okta Inc., Chris McKee