|
6 | 6 | - [Organizations](#organizations) |
7 | 7 | - [Extra parameters](#extra-parameters) |
8 | 8 | - [Roles](#roles) |
| 9 | +- [Multiple Custom Domains](#multiple-custom-domains) |
9 | 10 | - [Backchannel Logout](#backchannel-logout) |
10 | 11 | - [Blazor Server](#blazor-server) |
11 | 12 |
|
@@ -314,6 +315,161 @@ public IActionResult Admin() |
314 | 315 | } |
315 | 316 | ``` |
316 | 317 |
|
| 318 | +## Multiple Custom Domains |
| 319 | + |
| 320 | +The SDK supports scenarios where a single application needs to authenticate users against **multiple Auth0 tenants** or **custom domains**. This is useful for multi-tenant SaaS applications where each customer has their own Auth0 tenant. |
| 321 | + |
| 322 | +### Basic Configuration |
| 323 | + |
| 324 | +Enable Multiple Custom Domains by calling `WithCustomDomains()` and providing a `DomainResolver` function: |
| 325 | + |
| 326 | +```csharp |
| 327 | +services.AddAuth0WebAppAuthentication(options => |
| 328 | +{ |
| 329 | + options.Domain = Configuration["Auth0:Domain"]; |
| 330 | + options.ClientId = Configuration["Auth0:ClientId"]; |
| 331 | +}) |
| 332 | +.WithCustomDomains(options => |
| 333 | +{ |
| 334 | + options.DomainResolver = httpContext => |
| 335 | + { |
| 336 | + var host = httpContext.Request.Host.Host; |
| 337 | + |
| 338 | + // Route to different Auth0 tenants based on subdomain |
| 339 | + if (host.StartsWith("tenant-a.")) |
| 340 | + { |
| 341 | + return Task.FromResult("tenant-a.us.auth0.com"); |
| 342 | + } |
| 343 | + |
| 344 | + if (host.StartsWith("tenant-b.")) |
| 345 | + { |
| 346 | + return Task.FromResult("tenant-b.us.auth0.com"); |
| 347 | + } |
| 348 | + |
| 349 | + // Default domain |
| 350 | + return Task.FromResult("your-default-domain.us.auth0.com"); |
| 351 | + }; |
| 352 | +}); |
| 353 | +``` |
| 354 | + |
| 355 | +### Configuring the DomainResolver |
| 356 | + |
| 357 | +The `DomainResolver` function receives the `HttpContext` and returns the Auth0 domain as a string. You can inspect any aspect of the HTTP request. The resolver can perform simple lookups or complex operations like querying a database: |
| 358 | + |
| 359 | +```csharp |
| 360 | +options.DomainResolver = httpContext => |
| 361 | +{ |
| 362 | + // Option 1: Based on subdomain |
| 363 | + var host = httpContext.Request.Host.Host; |
| 364 | + var subdomain = host.Split('.')[0]; |
| 365 | + return Task.FromResult($"{subdomain}.us.auth0.com"); |
| 366 | + |
| 367 | + // Option 2: Based on path |
| 368 | + var path = httpContext.Request.Path.Value; |
| 369 | + if (path.StartsWith("/tenant-a")) |
| 370 | + return Task.FromResult("tenant-a.us.auth0.com"); |
| 371 | + |
| 372 | + // Option 3: Based on custom header |
| 373 | + var tenantHeader = httpContext.Request.Headers["X-Tenant-Id"].FirstOrDefault(); |
| 374 | + return Task.FromResult($"{tenantHeader}.us.auth0.com"); |
| 375 | + |
| 376 | + // Option 4: Based on cookie |
| 377 | + var tenantCookie = httpContext.Request.Cookies["tenant"]; |
| 378 | + return Task.FromResult($"{tenantCookie}.us.auth0.com"); |
| 379 | +}; |
| 380 | + |
| 381 | +// Option 5: Complex resolution with database lookup |
| 382 | +options.DomainResolver = async httpContext => |
| 383 | +{ |
| 384 | + var host = httpContext.Request.Host.Host; |
| 385 | + var tenantId = host.Split('.')[0]; |
| 386 | + |
| 387 | + // Look up tenant configuration from database |
| 388 | + var tenantService = httpContext.RequestServices |
| 389 | + .GetRequiredService<ITenantService>(); |
| 390 | + var tenant = await tenantService.GetTenantAsync(tenantId); |
| 391 | + |
| 392 | + return tenant?.Auth0Domain ?? "default.us.auth0.com"; |
| 393 | +}; |
| 394 | +``` |
| 395 | + |
| 396 | +### Caching Configuration |
| 397 | + |
| 398 | +Control how OpenID Connect configurations are cached for each domain using `ConfigurationManagerCache`. |
| 399 | + |
| 400 | +#### MemoryConfigurationManagerCache (Default) |
| 401 | + |
| 402 | +Caches configurations in memory with configurable size and expiration: |
| 403 | + |
| 404 | +```csharp |
| 405 | +.WithCustomDomains(options => |
| 406 | +{ |
| 407 | + options.DomainResolver = httpContext => { /* ... */ }; |
| 408 | + |
| 409 | + options.ConfigurationManagerCache = new MemoryConfigurationManagerCache( |
| 410 | + maxSize: 100, // Maximum number of domains to cache |
| 411 | + slidingExpiration: TimeSpan.FromHours(1) // Optional: cache entries expire after 1 hour of inactivity |
| 412 | + ); |
| 413 | +}); |
| 414 | +``` |
| 415 | + |
| 416 | +#### NullConfigurationManagerCache |
| 417 | + |
| 418 | +Disables caching entirely (not recommended for production): |
| 419 | + |
| 420 | +```csharp |
| 421 | +.WithCustomDomains(options => |
| 422 | +{ |
| 423 | + options.DomainResolver = httpContext => { /* ... */ }; |
| 424 | + options.ConfigurationManagerCache = new NullConfigurationManagerCache(); |
| 425 | +}); |
| 426 | +``` |
| 427 | + |
| 428 | +#### Custom Cache Implementation |
| 429 | + |
| 430 | +Implement `IConfigurationManagerCache` for custom caching strategies (e.g., Redis, distributed cache): |
| 431 | + |
| 432 | +```csharp |
| 433 | +public class RedisConfigurationManagerCache : IConfigurationManagerCache |
| 434 | +{ |
| 435 | + private readonly IDistributedCache _cache; |
| 436 | + |
| 437 | + public RedisConfigurationManagerCache(IDistributedCache cache) |
| 438 | + { |
| 439 | + _cache = cache; |
| 440 | + } |
| 441 | + |
| 442 | + public IConfigurationManager<OpenIdConnectConfiguration> GetOrCreate( |
| 443 | + string metadataAddress, |
| 444 | + Func<string, IConfigurationManager<OpenIdConnectConfiguration>> factory) |
| 445 | + { |
| 446 | + // Implement Redis-based caching logic |
| 447 | + } |
| 448 | + |
| 449 | + public void Clear() => _cache.Remove("oidc-configs"); |
| 450 | + public void Dispose() { } |
| 451 | +} |
| 452 | + |
| 453 | +// Usage |
| 454 | +.WithCustomDomains(options => |
| 455 | +{ |
| 456 | + options.DomainResolver = httpContext => { /* ... */ }; |
| 457 | + options.ConfigurationManagerCache = new RedisConfigurationManagerCache(distributedCache); |
| 458 | +}); |
| 459 | +``` |
| 460 | + |
| 461 | +### Important Considerations |
| 462 | + |
| 463 | +1. **Domain Resolution Timing**: The `DomainResolver` is called early in the request pipeline and the result is cached for the duration of the request. |
| 464 | + |
| 465 | +2. **Callback URLs**: Each Auth0 tenant must have the appropriate callback URLs configured: |
| 466 | + - **Allowed Callback URLs**: `https://{your-domain}/callback` |
| 467 | + - **Allowed Logout URLs**: `https://{your-domain}/` |
| 468 | + |
| 469 | +3. **Token Validation**: The SDK automatically validates that tokens come from the expected issuer (the domain returned by your `DomainResolver`). |
| 470 | + |
| 471 | +4. **Performance**: Use the default `MemoryConfigurationManagerCache` for most scenarios. The cache significantly reduces the overhead of fetching OIDC configuration for each request. |
| 472 | + |
317 | 473 | ## Backchannel Logout |
318 | 474 |
|
319 | 475 | Backchannel logout can be configured by calling `WithBackchannelLogout()` when calling `AddAuth0WebAppAuthentication`. |
|
0 commit comments