The @auth0/auth0-angular SDK is an Angular wrapper library for Auth0 authentication in Single Page Applications. It wraps the @auth0/auth0-spa-js library (v2.11.0+) and provides Angular-native APIs including RxJS observables, dependency injection, HTTP interceptors, and route guards. The SDK implements the OAuth 2.0 Authorization Code Flow with PKCE for secure authentication in browser-based applications.
Published Package: @auth0/auth0-angular on npm
Current Version: 2.5.0
Repository: https://github.com/auth0/auth0-angular
Purpose: This page introduces the SDK's architecture, relationship to @auth0/auth0-spa-js, repository structure, and core components. For installation instructions, see page 2.1. For configuration details, see page 2.2. For API documentation, see page 3. For integration patterns, see page 4.
Sources: README.md1-11 projects/auth0-angular/package.json1-38 projects/auth0-angular/src/useragent.ts1-2
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: Code Entity Mapping
Sources: projects/auth0-angular/src/lib/auth.service.ts1-500 projects/auth0-angular/src/lib/auth.guard.ts1-200 projects/auth0-angular/src/lib/auth.interceptor.ts1-300 projects/auth0-angular/src/lib/auth.module.ts1-100 projects/auth0-angular/src/lib/auth.config.ts1-237
<old_str> Dependency on @auth0/auth0-spa-js: Method Delegation
Wrapper Pattern
The Auth0ClientFactory in projects/auth0-angular/src/lib/auth.client.ts1-50 instantiates Auth0Client from @auth0/auth0-spa-js and provides it via Angular dependency injection as Auth0ClientService. The AuthService then:
Auth0ClientService to access the Auth0Client instanceauth.loginWithRedirect() → client.loginWithRedirect()from() and operatorsAuthState BehaviorSubject streams when authentication state changesAbstractNavigator for redirect handlingSources: projects/auth0-angular/package.json33-35 projects/auth0-angular/src/lib/auth.service.ts1-500 projects/auth0-angular/src/lib/auth.client.ts1-50 </old_str> <new_str> Core SDK Services and Their Methods
| Service File | Exported Classes/Functions | Primary Methods/Properties | Purpose |
|---|---|---|---|
auth.service.ts | AuthService | loginWithRedirect(), loginWithPopup(), logout(), getAccessTokenSilently(), handleRedirectCallback(), connectAccountWithRedirect(); Observables: isAuthenticated$, user$, idTokenClaims$, error$, isLoading$, appState$ | Main authentication service; wraps Auth0Client methods and exposes reactive streams |
auth.guard.ts | AuthGuard, authGuardFn() | canActivate(), canActivateChild(), canLoad() | Route protection; redirects unauthenticated users to login |
auth.interceptor.ts | AuthHttpInterceptor, authHttpInterceptorFn() | intercept(req, next) | HTTP interceptor; automatically attaches access tokens to matching requests |
auth.module.ts | AuthModule | forRoot(config?) | NgModule for traditional module-based configuration |
provider.ts | provideAuth0() | Returns provider array | Functional API for standalone component configuration |
auth.state.ts | AuthState | isAuthenticated$, user$, idTokenClaims$, error$, isLoading$, appState$ | Internal state management using RxJS BehaviorSubjects |
auth.config.ts | AuthConfig interface, AuthClientConfig, AuthConfigService token | set(config), get() | Configuration management; supports static and dynamic patterns |
auth.client.ts | Auth0ClientService token, Auth0ClientFactory | createClient(config) | Factory for creating and providing Auth0Client instance |
Sources: projects/auth0-angular/src/lib/auth.service.ts1-500 projects/auth0-angular/src/lib/auth.guard.ts1-200 projects/auth0-angular/src/lib/auth.interceptor.ts1-300 projects/auth0-angular/src/lib/auth.module.ts1-100 projects/auth0-angular/src/lib/provider.ts1-50 projects/auth0-angular/src/lib/auth.state.ts1-200 projects/auth0-angular/src/lib/auth.config.ts1-237 projects/auth0-angular/src/lib/auth.client.ts1-100
The SDK delegates all OAuth 2.0/OIDC protocol operations to @auth0/auth0-spa-js (version ^2.11.0). The Auth0ClientFactory instantiates an Auth0Client instance, which AuthService then wraps to provide Angular-specific functionality.
Delegation Pattern: Method Flow
Wrapped Methods
The following AuthService methods directly delegate to Auth0Client:
| AuthService Method | Auth0Client Method | Transform |
|---|---|---|
loginWithRedirect(options?) | loginWithRedirect(options) | Promise → Observable (using from()) |
loginWithPopup(options?) | loginWithPopup(options) | Promise → Observable |
logout(options?) | logout(options) | Promise → Observable; integrates with Angular Router |
handleRedirectCallback(url?) | handleRedirectCallback(url) | Promise → Observable; updates AuthState |
getAccessTokenSilently(options?) | getTokenSilently(options) | Promise → Observable; caches result |
getAccessTokenWithPopup(options?) | getTokenWithPopup(options) | Promise → Observable |
Angular-Specific Enhancements
The SDK adds these capabilities on top of Auth0Client:
isAuthenticated$, user$, idTokenClaims$ as BehaviorSubjects in AuthStateAbstractNavigator preserves target URLs across redirectsAuthHttpInterceptor automatically attaches tokens to matching HTTP requestsAuthGuard protects routes based on authentication statusauth0Client headerSources: projects/auth0-angular/src/lib/auth.service.ts1-500 projects/auth0-angular/src/lib/auth.client.ts1-100 projects/auth0-angular/src/lib/auth.state.ts1-200 projects/auth0-angular/package.json33-35
The repository is organized as an Angular workspace with two projects: the core library (auth0-angular) and a development playground application.
Workspace Structure
Directory Contents
| Path | Type | Purpose |
|---|---|---|
projects/auth0-angular/src/lib/ | Source | Core library code: services, guards, interceptors, configuration |
projects/auth0-angular/src/public-api.ts | Source | Public API surface; exports all user-facing types and services |
projects/auth0-angular/schematics/ | Tooling | Angular schematics for ng add @auth0/auth0-angular installation |
projects/auth0-angular/package.json | Config | Package metadata: name, version, dependencies, peer dependencies |
projects/playground/src/app/ | Application | Development app demonstrating SDK usage patterns |
projects/playground/cypress/ | Tests | End-to-end tests using Cypress |
dist/auth0-angular/ | Build output | Compiled library ready for npm publishing |
.github/workflows/ | CI/CD | GitHub Actions: test, BrowserStack, security scans, release |
Playground Application
The playground serves multiple purposes:
start:local script with local OIDC provider for offline developmentThe playground is configured in angular.json to depend on the local library build, allowing immediate testing of changes.
Sources: package.json1-90 projects/auth0-angular/package.json1-38 README.md1-240 [angular.json configuration]
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 is published to npm as @auth0/auth0-angular and includes Angular schematics for automated installation.
Package Metadata
Dependencies
| Package | Version Constraint | Type | Purpose |
|---|---|---|---|
@auth0/auth0-spa-js | ^2.11.0 | Direct | OAuth/OIDC client implementation |
tslib | ^2.0.0 | Direct | TypeScript runtime helpers |
@angular/common | >=13 | Peer | Angular common module (required by consuming app) |
@angular/core | >=13 | Peer | Angular core framework (required by consuming app) |
@angular/router | >=13 | Peer | Angular router (required by consuming app) |
Installation Methods
npm install:
Angular CLI schematic:
The ng add schematic (defined in projects/auth0-angular/schematics/) automates setup by:
app.config.ts or app.module.tsBuild Process
The library is compiled using ng-packagr, configured in projects/auth0-angular/ng-packagr.json:
.d.ts type definitionsdist/auth0-angular/User Agent Header
The SDK identifies itself to Auth0 via the auth0Client parameter. The version is defined in projects/auth0-angular/src/useragent.ts:
This is updated automatically by scripts/update-useragent.js during the build process.
Sources: projects/auth0-angular/package.json1-38 projects/auth0-angular/src/useragent.ts1-2 README.md29-40 package.json10-14
The SDK supports two primary configuration approaches: NgModule-based (for traditional apps) and standalone/functional (for modern Angular apps with standalone components).
Configuration API Comparison
Static Configuration (Compile-Time)
Static configuration is provided directly during app initialization:
Dynamic Configuration (Runtime)
Dynamic configuration loads settings from external sources (e.g., /config endpoint) before SDK initialization:
The dynamic approach is useful for:
For detailed configuration options, see page 2.2. For setup instructions, see page 2.1.
Sources: README.md64-176 projects/auth0-angular/src/lib/auth.config.ts170-237 projects/auth0-angular/src/lib/auth.module.ts1-100 projects/auth0-angular/src/lib/provider.ts1-50
Current Version: 2.5.0 (released January 13, 2026)
Latest Changes (v2.5.0):
connectAccountWithRedirect() method to AuthService for Auth0 Connected Accounts featureAngular Compatibility
The SDK supports actively supported Angular versions as defined in the Angular release schedule:
Peer Dependencies
Applications using this SDK must provide:
| Package | Version Constraint | Notes |
|---|---|---|
@angular/common | >=13 | Required for CommonModule, HTTP client |
@angular/core | >=13 | Required for dependency injection, lifecycle hooks |
@angular/router | >=13 | Required for AuthGuard, routing integration |
RxJS Compatibility
The SDK supports both RxJS 6 and RxJS 7, allowing gradual migration:
^6.6.7 (used in workspace: 6.6.7)^7.4.0Note: The workspace uses RxJS 6.6.7 (see package.json36), but the SDK is compatible with both major versions.
Browser Compatibility
The SDK inherits browser support from @auth0/auth0-spa-js. Supported browsers:
Node.js Compatibility (Development)
For SDK development and building:
Sources: projects/auth0-angular/package.json1-38 package.json27-39 CHANGELOG.md3-9 projects/auth0-angular/src/useragent.ts1-2 README.md24-26
AuthConfig and configuration patternsRefresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.
