The @auth0/auth0-angular SDK is an Angular library that provides authentication and authorization functionality for Single Page Applications (SPAs) by wrapping the Auth0 platform's authentication services. The SDK implements the OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange) and integrates seamlessly with Angular's dependency injection, routing, and HTTP systems.
Purpose and Scope: This page provides a high-level introduction to the SDK's architecture, core components, and design philosophy. For installation and configuration instructions, see Getting Started. For detailed API documentation of individual services, see Core SDK Components. For integration patterns and usage examples, see Integration Patterns and Examples and Guides.
The @auth0/auth0-angular SDK is built as a thin Angular-specific wrapper around the @auth0/auth0-spa-js library (version 2.11.0). This layered architecture allows the SDK to leverage the battle-tested authentication logic of the underlying SPA SDK while providing Angular-native APIs including RxJS observables, dependency injection services, HTTP interceptors, and route guards.
SDK Architecture Layers
Sources: README.md1-240 projects/auth0-angular/package.json1-38 Diagram 2 from system architecture
The SDK architecture consists of three main layers:
| Layer | Components | Responsibility |
|---|---|---|
| Application Interface | AuthService, AuthGuard, AuthHttpInterceptor, AuthModule, provideAuth0() | Provides Angular-native APIs that application code directly interacts with |
| State Management | AuthState, AuthClientConfig | Manages authentication state as RxJS observables and configuration |
| Client Abstraction | Auth0ClientService | Wraps the @auth0/auth0-spa-js client instance and handles initialization |
The SDK exposes five primary components through its public API, each serving a specific role in the authentication workflow:
Component Responsibilities
Sources: projects/auth0-angular/src/lib/auth.config.ts1-237 README.md204-209 Diagram 2 from system architecture
| Component | File Location | Purpose |
|---|---|---|
| AuthService | src/lib/auth.service.ts | Primary service providing methods for login (loginWithRedirect(), loginWithPopup()), logout, token retrieval (getAccessTokenSilently()), and observable streams for authentication state |
| AuthGuard | src/lib/auth.guard.ts | Angular route guard implementing CanActivate, CanActivateChild, and CanLoad to protect routes from unauthenticated access |
| AuthHttpInterceptor | src/lib/auth.interceptor.ts | Angular HTTP interceptor that automatically attaches access tokens to outgoing HTTP requests based on a configured allowlist |
| AuthModule | src/lib/auth.module.ts | NgModule providing .forRoot() static method for traditional module-based configuration |
| AuthState | src/lib/auth.state.ts | Internal service managing reactive state with RxJS observables including isAuthenticated$, user$, idTokenClaims$, and error$ |
| AuthClientConfig | src/lib/auth.config.ts | Service for managing SDK configuration, supporting both static and dynamic configuration patterns |
The SDK depends on @auth0/auth0-spa-js version ^2.11.0 as its core authentication engine. All authentication operations—including login redirects, token exchanges, token caching, and silent authentication—are delegated to the underlying Auth0Client instance from this library.
Auth0Client Delegation Pattern
Sources: projects/auth0-angular/package.json33-35 Diagram 2 from system architecture
The Auth0ClientService initializes and maintains a singleton instance of Auth0Client, providing it to AuthService. The Angular-specific services add functionality on top of the base client:
The repository is organized as an Angular monorepo with two distinct projects:
Project Structure
Sources: README.md1-240 projects/auth0-angular/package.json1-38 Diagram 1 from system architecture
| Directory | Purpose |
|---|---|
projects/auth0-angular/ | The library package published to npm as @auth0/auth0-angular. Contains all production code, configuration interfaces, and services |
projects/playground/ | Development and testing application that consumes the library. Used for manual testing and E2E test execution |
.github/workflows/ | CI/CD automation including test execution, BrowserStack integration, security scanning, and release management |
dist/auth0-angular/ | Build output directory containing the compiled library ready for npm publishing |
The library package is built using ng-packagr, which compiles TypeScript, generates type definitions, and creates distribution bundles compatible with Angular's package format.
The SDK supports two configuration patterns: static configuration provided at application bootstrap and dynamic configuration loaded asynchronously before SDK initialization.
Configuration Flow
Sources: README.md63-177 projects/auth0-angular/src/lib/auth.config.ts165-237 Diagram 5 from system architecture
The AuthClientConfig service acts as the central configuration repository. It implements an injectable service that can receive configuration either:
AuthModule.forRoot(config) or provideAuth0(config) during module/provider setupAPP_INITIALIZER factory that loads configuration from an external source (file, API endpoint) before the SDK initializesThe dynamic configuration pattern uses HttpBackend directly rather than HttpClient to avoid triggering the AuthHttpInterceptor, which would create a circular dependency since the interceptor requires configuration to function.
Applications integrate the SDK through Angular's standard patterns:
Module-Based Applications (Traditional)
Standalone Applications (Modern)
Integration Points
| Integration Point | Mechanism | Purpose |
|---|---|---|
| Authentication operations | Inject AuthService | Call methods like loginWithRedirect(), logout(), getAccessTokenSilently() |
| Reactive state | Subscribe to AuthService observables | React to changes in isAuthenticated$, user$, error$ |
| Route protection | Apply AuthGuard or authGuardFn | Prevent unauthenticated access to routes |
| API calls | Configure AuthHttpInterceptor | Automatically attach access tokens to HTTP requests |
For detailed integration instructions, see Module-Based Setup and Functional API (Standalone Components).
The SDK implements the OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange), which is the recommended flow for Single Page Applications. The flow involves:
PKCE Implementation
Sources: README.md1-11 projects/auth0-angular/package.json7-10 Diagram 6 from system architecture
The underlying @auth0/auth0-spa-js library handles all PKCE mechanics including:
The Angular SDK does not need to implement these details; it delegates entirely to the underlying Auth0 SPA SDK.
Current Version: 2.4.1
Supported Angular Versions: The SDK supports all actively supported versions of Angular as defined in the Angular release schedule. As of the latest release, this includes Angular 13 and higher.
Peer Dependencies:
@angular/common: >=13@angular/core: >=13@angular/router: >=13Direct Dependencies:
@auth0/auth0-spa-js: ^2.11.0tslib: ^2.0.0Sources: projects/auth0-angular/package.json1-38 README.md24-26 projects/auth0-angular/src/useragent.ts1-2
AuthConfig and configuration patternsRefresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.