The auth0-angular SDK is an Angular library that integrates Auth0 authentication and authorization into Angular single-page applications. This page provides a high-level introduction to the SDK's architecture, core components, and capabilities. It serves as an entry point for understanding how the SDK works and how it fits into an Angular application.
For installation and initial configuration instructions, see Getting Started. For detailed documentation of individual services and APIs, see Core SDK Components. For advanced authentication scenarios, see Advanced Features.
Sources: README.md1-20 projects/auth0-angular/package.json1-38
The auth0-angular SDK is a wrapper around @auth0/auth0-spa-js (version 2.14.0) that provides Angular-specific bindings and integration patterns. The SDK handles OAuth 2.0 and OpenID Connect (OIDC) authentication flows, including:
The SDK is published as @auth0/auth0-angular on NPM and supports Angular version 13 and above (currently tested with Angular 19.2.18).
Sources: README.md3-4 package.json27-38 projects/auth0-angular/package.json28-35
Diagram: SDK Architecture and Integration Points
The SDK acts as a bridge between your Angular application and Auth0's authentication services. Configuration flows through AuthModule.forRoot() (for NgModule apps) or provideAuth0() (for standalone apps), which initializes the SDK's core services via Angular's dependency injection system. AuthService orchestrates all authentication operations while delegating the actual OAuth/OIDC protocol handling to the underlying Auth0Client from @auth0/auth0-spa-js.
Sources: README.md64-139 Diagram 2 from high-level architecture
The SDK consists of several interconnected components that work together to provide authentication functionality:
| Component | Type | Purpose | Key Methods/Properties |
|---|---|---|---|
AuthService | Service | Main API for authentication operations | loginWithRedirect(), logout(), getAccessTokenSilently(), isAuthenticated$, user$ |
AuthModule | NgModule | Module-based configuration and DI setup | forRoot(config) static method |
provideAuth0() | Function | Functional configuration for standalone components | Called in ApplicationConfig.providers |
AuthClientConfig | Service | Dynamic configuration management | set(config), get() |
AuthGuard | Guard | Route protection for NgModule apps | canActivate, canActivateChild, canLoad |
authGuardFn() | Function | Functional route guard for standalone apps | Returns CanActivateFn |
AuthHttpInterceptor | Interceptor (class-based) | Automatic token attachment for NgModule apps | Configured via httpInterceptor property |
authHttpInterceptorFn() | Function | Functional HTTP interceptor for standalone apps | Returns HttpInterceptorFn |
Auth0ClientService | Service (internal) | Wrapper around Auth0Client from SPA SDK | Manages underlying Auth0Client instance |
AuthState | Service (internal) | Reactive state management | Manages BehaviorSubject and ReplaySubject instances |
Sources: projects/auth0-angular/src/lib/auth.config.ts1-237 Diagram 1 from high-level architecture
Diagram: Configuration Structure
The AuthConfig interface (projects/auth0-angular/src/lib/auth.config.ts107-137) extends Auth0ClientOptions from the underlying SPA SDK and adds Angular-specific configuration options. Configuration can be provided statically at initialization or loaded dynamically using APP_INITIALIZER (NgModule) or provideAppInitializer() (standalone).
Sources: projects/auth0-angular/src/lib/auth.config.ts107-237 README.md64-177
The SDK supports multiple authentication methods:
AuthService.loginWithRedirect() - redirects to Auth0 Universal Login pageAuthService.loginWithPopup() - opens login in a popup windowAuthService.getAccessTokenSilently() - obtains tokens without user interactionSources: README.md179-202 Diagram 2 from high-level architecture
The SDK provides automatic token caching and renewal:
cacheLocation propertyuseRefreshTokens configurationignoreCache, cacheMode for fine-grained controlFor detailed information on token management strategies, see Token Management and Caching.
Sources: projects/auth0-angular/src/lib/auth.config.ts1-6 Section 5.2 reference
Diagram: Reactive State Management
The SDK exposes authentication state through RxJS observables on AuthService. Applications subscribe to these observables to react to authentication state changes. State updates occur automatically when users log in, log out, or when tokens are refreshed.
Sources: Section 3.3 reference for AuthState details
The SDK provides two approaches for protecting routes:
NgModule Approach - using AuthGuard class:
Standalone Approach - using authGuardFn() function:
For detailed guard configuration and custom implementations, see Route Guards.
Sources: Section 4.4 reference
The AuthHttpInterceptor automatically attaches access tokens to outgoing HTTP requests that match configured patterns:
uriMatcher functionsallowAnonymousConfiguration example structure:
For comprehensive HTTP interceptor configuration, see HTTP Interceptor Configuration.
Sources: projects/auth0-angular/src/lib/auth.config.ts44-102 Section 4.3 reference
The SDK supports both traditional NgModule-based and modern standalone component architectures:
For a detailed comparison of these approaches and when to use each, see NgModule vs Standalone Components.
Sources: README.md64-109 Section 4.2 reference
The SDK identifies itself to Auth0 servers using a custom user-agent header that includes both the SDK version and the Angular version. This is automatically constructed and sent with authentication requests:
The user-agent version is updated automatically during the build process via the update-useragent prebuild script, which runs before every build to ensure version consistency.
Sources: projects/auth0-angular/useragent.ts1 package.json10-23
Breaking Changes: Version 2.x introduced significant breaking changes from v1.x. For migration guidance, see Migration Guide.
Sources: projects/auth0-angular/package.json1-38 package.json27-38 projects/auth0-angular/useragent.ts1 CHANGELOG.md98-136
Recent Additions: Version 2.6.0 added loginWithCustomTokenExchange() method and improved type safety with makeEnvironmentProviders() to prevent component-level usage of provideAuth0().
Breaking Changes: Version 2.x introduced significant breaking changes from v1.x. For migration guidance, see Migration Guide.
Sources: projects/auth0-angular/package.json3 package.json27-79 CHANGELOG.md3-13
The SDK is built using Angular's standard library build tooling:
The SDK wraps version 2.14.0 of @auth0/auth0-spa-js, which provides the core OAuth 2.0 and OIDC protocol implementation. The Auth0ClientService (internal service) manages the underlying Auth0Client instance. The Angular SDK adds:
AbstractNavigatorAuthModule.forRoot()) and standalone (provideAuth0()) patternsAll authentication operations ultimately delegate to the Auth0Client class from the underlying SPA SDK via Auth0ClientService. Configuration options that are part of Auth0ClientOptions are passed through directly to the SPA SDK.
Sources: package-lock.json808-819 projects/auth0-angular/package.json33-35 Diagram 2 from high-level architecture </old_str>
<old_str>
ng-packagr for Angular Package Format (APF) compliance@auth0/auth0-angularng-add schematic for CLI installation
</old_str>
<new_str>ng-packagr v19.2.2 for Angular Package Format (APF) compliance@auth0/auth0-angularng-add schematic for automated CLI installation and configurationFor detailed build information, see Build System. For release procedures, see Release Process.
Sources: package.json10-15 projects/auth0-angular/package.json14-17 Diagram 3 from high-level architecture
To start using the SDK in your application:
For practical code examples, see Common Integration Patterns. For troubleshooting, see FAQ and Troubleshooting.
Sources: README.md sections referenced in Next Steps
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.
