This document provides a comprehensive introduction to the Auth0.AspNetCore.Authentication library, including its architecture, capabilities, and role in ASP.NET Core applications. This page covers the high-level design, component structure, and feature overview. For detailed setup instructions, see Getting Started. For configuration reference, see Configuration Options Reference. For advanced features like backchannel logout and PAR, see Advanced Features.
Auth0.AspNetCore.Authentication is a NuGet package that provides authentication middleware for ASP.NET Core applications integrating with Auth0's identity platform. The library is built on top of Microsoft.AspNetCore.Authentication.OpenIdConnect and simplifies the integration process by providing Auth0-specific defaults, configuration patterns, and advanced features.
Current Version: 1.6.1
Package Identity: Auth0.AspNetCore.Authentication
Primary Entry Points:
ServiceCollectionExtensions.AddAuth0WebAppAuthentication() - extends IServiceCollectionAuthenticationBuilderExtensions.AddAuth0WebAppAuthentication() - extends AuthenticationBuilderThe library supports multiple .NET versions through multi-targeting: .NET 6.0, 7.0, 8.0, and 10.0.
Sources: src/Auth0.AspNetCore.Authentication/Auth0.AspNetCore.Authentication.csproj1-57 README.md1-10
The library consists of several layers that build upon Microsoft's OpenID Connect middleware:
Diagram: Component Architecture and Dependencies
Sources: README.md77-83 src/Auth0.AspNetCore.Authentication/Auth0.AspNetCore.Authentication.csproj27-45
Diagram: Namespace and Class Organization
Sources: src/Auth0.AspNetCore.Authentication/Auth0.AspNetCore.Authentication.csproj1-57
The library extends and configures Microsoft's OpenID Connect middleware rather than replacing it. This approach provides Auth0-specific defaults while maintaining compatibility with standard OIDC features.
Diagram: Integration with Microsoft OpenID Connect Middleware
The library intercepts OpenID Connect events at key extension points:
Sources: README.md1-3 docs-source/index.md1-3
The library provides the following core capabilities:
| Feature | Description | Configuration Component |
|---|---|---|
| Cookie & OpenID Connect Authentication | Hybrid authentication using cookies for sessions and OIDC for authorization | Auth0WebAppOptions |
| Automatic Logout URL Configuration | Configures Auth0 logout endpoint with proper redirect URIs | LogoutAuthenticationPropertiesBuilder |
| Access Token Retrieval | Authorization Code Flow with PKCE for API access | Auth0WebAppWithAccessTokenOptions |
| Automatic Token Refresh | Transparent access token refresh using refresh tokens | TokenClient |
| Backchannel Logout | OIDC Back-Channel Logout 1.0 support | BackchannelLogoutHandler |
| Pushed Authorization Requests (PAR) | OAuth 2.0 PAR (RFC 9126) for enhanced security | PushedAuthorizationRequestHandler |
| Organization Support | Multi-tenant organization validation | Auth0WebAppOptions.Organization |
| Client Assertion with JWT | JWT-based client authentication alternative to client secrets | JwtTokenFactory |
| Custom Parameters | Support for Auth0-specific and custom authentication parameters | LoginAuthenticationPropertiesBuilder |
| Event Pipeline Access | Full access to OpenID Connect event handlers | Auth0WebAppWithAccessTokenEvents |
Sources: CHANGELOG.md142-148 README.md1-10
The library implements a sophisticated multi-targeting approach to support four .NET versions simultaneously:
Diagram: Multi-Framework Targeting and Dependency Resolution
The project file uses conditional package references based on the target framework:
This produces a single NuGet package containing all four framework versions, with NuGet automatically selecting the appropriate version at restore time.
For detailed information about version support and dependency management, see Multi-Framework Support and Dependencies.
Sources: src/Auth0.AspNetCore.Authentication/Auth0.AspNetCore.Authentication.csproj3-17 CHANGELOG.md14
Applications integrate the library by calling one of two extension methods during service registration:
Method 1: IServiceCollection Extension
Location: ServiceCollectionExtensions.AddAuth0WebAppAuthentication()
Method 2: AuthenticationBuilder Extension
Location: AuthenticationBuilderExtensions.AddAuth0WebAppAuthentication()
Both methods return an Auth0WebAppAuthenticationBuilder instance that provides fluent configuration:
Diagram: Builder Pattern API Surface
Sources: README.md75-83
Applications trigger authentication flows using ASP.NET Core's HttpContext:
Login Flow:
Logout Flow:
The constant Auth0Constants.AuthenticationScheme defaults to "Auth0" and identifies the authentication scheme.
For detailed authentication flow documentation, see Authentication Flows.
Sources: README.md86-111
The library uses a layered configuration model:
Diagram: Configuration Class Hierarchy
Configuration Levels:
Auth0WebAppOptions): Set once at startup, loaded from appsettings.jsonLoginAuthenticationPropertiesBuilder, LogoutAuthenticationPropertiesBuilder): Dynamic properties for individual authentication requestsOpenIdConnectOptions, CookieAuthenticationOptions): Automatically configured based on Auth0 optionsFor comprehensive configuration reference, see Configuration Options Reference.
Sources: README.md55-83
The library orchestrates a standard OpenID Connect Authorization Code flow with Auth0-specific enhancements:
Diagram: High-Level Authentication Flow
Key Flow Components:
LoginAuthenticationPropertiesBuilder: Constructs authentication request parametersPushedAuthorizationRequestHandler: Handles PAR pre-authorization (if enabled)JwtTokenFactory: Creates client assertions for confidential clientsIdTokenValidator: Validates ID token claims and signaturesTokenClient: Stores tokens and handles refresh operationsFor detailed flow documentation, see Login Flow, Logout Flow, and Access Token Retrieval.
Sources: README.md86-111
The library provides transparent token lifecycle management:
Diagram: Token Management and Refresh Lifecycle
Token Management Components:
TokenClient: Handles refresh token operations via /oauth/token endpointAuth0WebAppWithAccessTokenEvents.OnMissingRefreshToken: Event handler when refresh token is unavailableAuth0WebAppWithAccessTokenOptions.UseRefreshTokens: Configuration flag to enable automatic refreshFor detailed token management documentation, see Token Management and Refresh.
Sources: CHANGELOG.md193 README.md143-148
The library implements multiple security layers:
| Security Feature | Implementation | Purpose |
|---|---|---|
| RS256 Signature Validation | IdTokenValidator with JWKS endpoint | Verify token authenticity |
| Issuer Validation | Claims validation against Auth0WebAppOptions.Domain | Prevent token substitution |
| Audience Validation | Validates aud claim matches ClientId or Audience | Ensure tokens are for this application |
| Organization Validation | Validates org_id or org_name claims | Multi-tenant security |
| PKCE | Automatic Proof Key for Code Exchange | Protect against authorization code interception |
| Client Assertions | JWT-based client authentication via JwtTokenFactory | Alternative to client secrets |
| Pushed Authorization Requests | PushedAuthorizationRequestHandler | Protect authorization parameters |
| Backchannel Logout | BackchannelLogoutHandler and ILogoutTokenHandler | Centralized session termination |
For detailed security documentation, see Token Validation and Security and Advanced Features.
Sources: README.md38-43 CHANGELOG.md48-50
The library includes comprehensive testing support:
Diagram: Testing Infrastructure and Mock Components
The testing infrastructure enables full integration testing without external Auth0 dependencies.
For detailed testing guidance, see Testing and related subsections.
Sources: CHANGELOG.md1-197
This introduction provides a high-level overview of the Auth0.AspNetCore.Authentication library. For specific topics, refer to:
Sources: README.md1-155 docs-source/index.md1-153
Refresh this wiki