Auth0.AspNetCore.Authentication.Api 1.0.0-beta.5

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 and Multiple Custom Domains support. Simplify your Auth0 JWT authentication integration for ASP.NET Core APIs with Auth0-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
  • Multiple Custom Domain (MCD) Support
    • Configuration
    • Security requirements
  • 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
• Multiple Custom Domains - Accept tokens from multiple Auth0 Custom Domains.
• Auth0 Optimized - Pre-configured for Auth0'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 8.0 and above.

Installation

Install the package via NuGet Package Manager:

dotnet add package Auth0.AspNetCore.Authentication.Api

Or via the Package Manager Console:

Install-Package Auth0.AspNetCore.Authentication.Api

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["Auth0:Domain"]}";
        options.Audience = builder.Configuration["Auth0:Audience"];
    });

After:

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0: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

Complete Migration Guide

For detailed migration instructions including:

• 8 migration scenarios (basic to complex)
• Custom events and validation
• Multiple audiences
• Testing strategies
• Rollback procedures
• Troubleshooting (10+ common issues)

See the Complete Migration Guide

Getting Started

Basic Configuration

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

using Auth0.AspNetCore.Authentication.Api;

using Microsoft.AspNetCore.Authentication.JwtBearer;

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

// Adds Auth0 JWT validation to the API
builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0: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:

{
  "Auth0": {
    "Domain": "your-tenant.auth0.com",
    "Audience": "https://your-api-identifier"
  }
}

Required Settings:

• Domain: Your Auth0 domain (e.g., my-app.auth0.com) - without the https:// prefix
• Audience: The API identifier configured in your Auth0 Dashboard

The library automatically constructs the authority URL as https://{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 Auth0-protected APIs.

Learn more about DPoP: Auth0 DPoP Documentation

Enabling DPoP

Enable DPoP with a single method call:

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0: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.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0: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:

Learn more: See detailed DPoP examples and use cases in EXAMPLES.md

Advanced Features

Multiple Custom Domain (MCD) Support

Multiple Custom Domains (MCD) lets you accept tokens from multiple Auth0 custom domains while keeping a single SDK instance. This is useful when one application serves multiple custom domains, each mapped to a different Auth0 custom domain.

Key capabilities:

• Static Domain Lists - Configure a fixed set of allowed Auth0 custom domains at startup
• Dynamic Domain Resolution - Resolve allowed domains at runtime based on request context, database queries, or external APIs
• Automatic OIDC Discovery - Handles OIDC metadata and JWKS fetching per domain with built-in caching
• Performance Optimized - In-memory cache with configurable expiration reduces network calls
• Security First - Validates token issuer before any network calls, rejects symmetric algorithms

Configuration

builder.Services.AddAuth0ApiAuthentication(options =>
{
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0:Audience"]
    };
})
.WithCustomDomains(options =>
{
    // Example: resolve from a request header
    options.DomainsResolver = async (httpContext, cancellationToken) =>
    {
        var tenantService = httpContext.RequestServices.GetRequiredService<ITenantService>();
        return await tenantService.GetAllowedDomainsAsync(cancellationToken);
    };
});

For detailed configuration options, caching strategies, security requirements, and more examples, see EXAMPLES.md - Multiple Custom Domains.

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.AddAuth0ApiAuthentication(options =>
{
    options.Domain = builder.Configuration["Auth0:Domain"];
    options.JwtBearerOptions = new JwtBearerOptions
    {
        Audience = builder.Configuration["Auth0: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!

Security requirements

When configuring the DomainsResolver, you are responsible for ensuring that all resolved domains are trusted. Mis-configuring the domain resolver is a critical security risk that can lead to authentication bypass on the relying party (RP) or expose the application to Server-Side Request Forgery (SSRF).

Single tenant limitation: The DomainsResolver is intended solely for multiple custom domains belonging to the same Auth0 tenant. It is not a supported mechanism for connecting multiple Auth0 tenants to a single application.

Secure proxy requirement: When using MCD, your application must be deployed behind a secure edge or reverse proxy (e.g., Cloudflare, Nginx, or AWS ALB). The proxy must be configured to sanitize and overwrite Host and X-Forwarded-Host headers before they reach your application.

Without a trusted proxy layer to validate these headers, an attacker can manipulate the domain resolution process. This can result in malicious redirects, where users are sent to unauthorized or fraudulent endpoints during the authentication flows.

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
• Multiple Custom Domains - Static domain lists, dynamic resolution, cache configuration
• 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/auth0/aspnetcore-api.git
cd aspnetcore-api
dotnet restore Auth0.AspNetCore.Authentication.Api.sln
dotnet build Auth0.AspNetCore.Authentication.Api.sln --configuration Release

Running Tests

Run the unit test suite:

dotnet test tests/Auth0.AspNetCore.Authentication.Api.UnitTests/

Playground Application

The repository includes a playground application for testing both standard JWT Bearer and DPoP authentication:

Setup

1. Configure Auth0 settings in Auth0.AspNetCore.Authentication.Api.Playground/appsettings.json:

   {
     "Auth0": {
       "Domain": "your-tenant.auth0.com",
       "Audience": "https://your-api-identifier"
     }
   }
   

2. Run the playground:

   cd Auth0.AspNetCore.Authentication.Api.Playground
   dotnet run
   

3. Access the application:

   • Swagger UI: https://localhost:7190/swagger
   • Open endpoint: GET /open-endpoint (no authentication required)
   • Protected endpoint: GET /restricted-endpoint (requires authentication)

Testing with Postman

The playground includes a pre-configured Postman collection (Auth0.AspNetCore.Authentication.Api.Playground.postman_collection.json) with ready-to-use requests:

1. Import the collection into Postman
2. Obtain a JWT token from Auth0
3. Set the {{token}} variable in your Postman environment
4. Test both endpoints with pre-configured headers

See the Playground README for detailed testing instructions and examples.

Contributing

We appreciate your contributions! Please review our contribution guidelines before submitting pull requests.

Contribution Checklist

• ✅ Read the Auth0 General Contribution Guidelines
• ✅ Read the Auth0 Code of Conduct
• ✅ Ensure all tests pass
• ✅ Add tests for new functionality
• ✅ Update documentation as needed
• ✅ Sign all commits

Support

If you have questions or need help:

• 📖 Check the Auth0 Documentation
• � See EXAMPLES.md for code examples
• 💬 Visit the Auth0 Community
• 🐛 Report issues on GitHub Issues

License

Copyright 2025 Okta, Inc.

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

Authors Okta Inc.

<p align="center"> <picture> <source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150"> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150"> <img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150"> </picture> </p> <p align="center">Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out <a href="https://auth0.com/why-auth0">Why Auth0?</a></p> <p align="center">This project is licensed under the Apache License 2.0. See the <a href="./LICENSE">LICENSE</a> file for more info.</p>