Adds support for Multiple Custom Domains

[kailash-b]

✏️ Changes

This PR adds Multiple Custom Domains support.

Added:

• Auth0CustomDomainsConfigurationManager - Core configuration manager that maintains separate OIDC configurations per domain with automatic discovery and JWKS fetching
• Auth0CustomDomainsOptions - Configuration class supporting both static domain lists (Domains) and dynamic runtime resolution (DomainsResolver)
• IConfigurationManagerCache interface with two implementations:
  • MemoryConfigurationManagerCache - In-memory cache with configurable size and sliding expiration (default: 100 entries, 10 min)
  • NullConfigurationManagerCache - No-op cache for testing or scenarios requiring fresh config on every request
• TokenValidationHelper - Pre-validation utility that extracts and validates token issuer before any network calls, rejects symmetric algorithms (HS256/HS384)
• Auth0CustomDomainsPostConfigureOptions - IPostConfigureOptions implementation for setting custom ConfigurationManager
• CustomDomainsEventsFactory - Event handler factory for chaining custom domains validation with existing JWT Bearer events
• MessageReceivedHandler - Event handler for early token validation in MessageReceived pipeline
• Extension method WithCustomDomains() on Auth0ApiAuthenticationBuilder for fluent API

Modified:

• AuthenticationBuilderExtensions.cs - Added custom domains configuration and validation logic
• Auth0Constants.cs - Added CustomDomains.Error.Description constants for error handling
• README.md - Added "Multiple Custom Domains Support" section under Advanced Features
• EXAMPLES.md - Reorganized with numbered sections, added section 4 with 3 comprehensive examples:
  • Static domain list configuration
  • Dynamic domain resolution with HttpContext
  • Custom cache configuratio

🔗 References

N/A

🎯 Testing

• Adds Unit and Integration test cases

• This change adds unit test coverage

• This change adds integration test coverage

• This change has been tested on the latest version (.NET 8.0)

✅ Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors
• All commits are signed

[Copilot]

Pull request overview

This PR adds support for Multiple Custom Domains to enable multi-tenant architectures where APIs need to accept JWT tokens from multiple Auth0 custom domains. The implementation includes a custom configuration manager that maintains separate OIDC configurations per domain, with both static domain lists and dynamic runtime resolution support.

Changes:

• Added Auth0CustomDomainsConfigurationManager with automatic OIDC discovery and JWKS fetching per domain
• Implemented two cache strategies: MemoryConfigurationManagerCache (default) and NullConfigurationManagerCache (no-op)
• Added pre-validation via MessageReceivedHandler to reject invalid tokens before network calls
• Extended Auth0ApiAuthenticationBuilder with fluent WithCustomDomains() API
• Updated documentation with comprehensive examples and integration patterns

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
AuthenticationBuilderExtensions.cs	Added WithCustomDomains() extension method and validation logic
Auth0CustomDomainsConfigurationManager.cs	Core configuration manager implementing per-domain OIDC configuration
Auth0CustomDomainsOptions.cs	Configuration class supporting static domains and dynamic resolution
TokenValidationHelper.cs	Pre-validation utility for token extraction and issuer validation
IConfigurationManagerCache.cs	Cache abstraction with two implementations
MemoryConfigurationManagerCache.cs	In-memory cache with size limits and sliding expiration
NullConfigurationManagerCache.cs	No-op cache implementation
DisposableConfigurationManagerWrapper.cs	Wrapper managing HttpClient lifecycle
MessageReceivedHandler.cs	Event handler for early token validation in pipeline
CustomDomainsEventsFactory.cs	Factory for creating chained JWT Bearer events
Auth0CustomDomainsPostConfigureOptions.cs	IPostConfigureOptions for injecting custom ConfigurationManager
Auth0Constants.cs	Added error description constants for custom domains
README.md	Added feature overview and key capabilities section
EXAMPLES.md	Reorganized structure and added three comprehensive custom domains examples
Test files	Added comprehensive unit and integration tests

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.