How manfredsteyer/angular-oauth2-oidc works
Purpose and package surface
This monorepo delivers Angular client libraries for OAuth 2/OIDC, centered on authorization-code flow with PKCE while retaining implicit and password flows. The primary npm library is exported from projects/lib/src/public_api.ts; its Angular module/provider integration begins in projects/lib/src/angular-oauth-oidc.module.ts and projects/lib/src/provider.ts.
A separate optional JWKS package supports signature validation for use cases such as implicit flow: projects/angular-oauth2-oidc-jwks/src/public-api.ts and projects/angular-oauth2-oidc-jwks/src/lib/jwks-validation-handler.ts.
Consumer integration boundary
Applications configure authentication behavior through the AuthConfig contract and register either NgModule or standalone providers. This boundary accepts issuer, client, redirect, scopes, flow, storage, validation, and resource-server settings.
• projects/lib/src/auth.config.ts
• projects/lib/src/angular-oauth-oidc.module.ts
• projects/lib/src/provider.ts
The library depends on Angular DI and HttpClient; consumers own bootstrap, routing, and their identity-provider registration.
OAuth orchestration core
OAuthService is the control-plane façade. Consumers configure it, load discovery metadata, start login redirects, consume callback parameters, manage tokens, retrieve user info, refresh/revoke/logout, and observe OAuth events.
• projects/lib/src/oauth-service.ts
• projects/lib/src/events.ts
• projects/lib/src/tokens.ts
Primary flow: application bootstrap → configure service → fetch discovery document → redirect to authorization server → browser callback returns to SPA → service exchanges/parses tokens and persists them → consumers call APIs or react to emitted events.
Protocol and trust boundary
Discovery, authorization, token, userinfo, revocation, and logout endpoints are external identity-provider services. URL construction and callback/query/fragment parsing are isolated in:
• projects/lib/src/url-helper.service.ts
• projects/lib/src/encoder.ts
• projects/lib/src/types.ts
The service must treat browser-returned parameters and remote discovery/token responses as untrusted until protocol/state/nonce and configured validation checks complete.
Token lifecycle and validation
The core library models token responses and supports configurable validation handlers, hashing, clock abstraction, browser storage, expiration checks, refresh scheduling, and silent refresh. Default validation can be replaced through DI/configuration.
• projects/lib/src/tokens.ts
• projects/lib/src/token-validation/validation-handler.ts
• projects/lib/src/token-validation/null-validation-handler.ts
Cryptographic JWT/JWKS signature validation is deliberately split into the optional package, keeping the recommended code-flow bundle smaller:
• projects/angular-oauth2-oidc-jwks/src/lib/jwks-validation-handler.ts
• projects/lib/src/token-validation/hash-handler.ts
Protected-resource integration
The HTTP interceptor is the boundary from Angular application requests to protected resource servers. It applies an access token only to configured allowed URL prefixes and delegates error handling through configurable resource-server hooks.
• projects/lib/src/interceptors/default-oauth.interceptor.ts
• projects/lib/src/interceptors/resource-server-error-handler.ts
• projects/lib/src/oauth-module.config.ts
Executable examples and documentation
Angular demo applications are integration entry points rather than production runtime components. The full sample exercises multiple OAuth configurations, routing, guards, silent refresh, and API calls; quickstarts show minimal module and standalone setups.
• projects/sample/src/main.ts
• projects/sample/src/app/app.module.ts
• projects/sample/src/app/auth-code-flow.config.ts
• projects/quickstart-demo/src/main.ts
• projects/quickstart-standalone/src/main.ts
Documentation source is maintained under docs-src/; generated API/site output lives under docs/.
Main entry points: oauth-service.ts OAuthService · public_api.ts Primary npm package · default-oauth.interceptor.ts OAuth HTTP interceptor · angular-oauth-oidc.module.ts Angular module
Components 19
Consumer applications
Applications own bootstrap, routing, and identity-provider registration.
- AuthConfig + DI registration · Configures issuer, client, redirect, scopes, flows, storage, validation, and resources.
projects/lib/src/auth.config.ts
Core OAuth library
- Angular module
projects/lib/src/angular-oauth-oidc.module.ts - Standalone providers
projects/lib/src/provider.ts - Primary npm package
projects/lib/src/public_api.ts - OAuthService · Coordinates login, callbacks, tokens, refresh, logout, and events.
projects/lib/src/oauth-service.ts - OAuth events
projects/lib/src/events.ts - Token lifecycle · Models tokens, persistence, expiry, refresh scheduling, and silent refresh.
projects/lib/src/tokens.ts - Validation handlers · Default validation is replaceable through DI or configuration.
projects/lib/src/token-validation/validation-handler.ts - Hash handler
projects/lib/src/token-validation/hash-handler.ts - OAuth HTTP interceptor · Adds access tokens only for configured allowed URL prefixes.
projects/lib/src/interceptors/default-oauth.interceptor.ts - Resource-server hooks
projects/lib/src/interceptors/resource-server-error-handler.ts
Protocol and trust boundary
- URL and callback parsing · Builds endpoint URLs and parses query or fragment callback values.
projects/lib/src/url-helper.service.ts - Identity provider · Discovery, authorization, token, userinfo, revocation, and logout services.
- Protected resource servers
Optional validation package
- JWKS package export
projects/angular-oauth2-oidc-jwks/src/public-api.ts - JWKS validation handler · Optional cryptographic signature validation for token flows such as implicit.
projects/angular-oauth2-oidc-jwks/src/lib/jwks-validation-handler.ts
Examples and docs
- Full sample app · Exercises configurations, guards, silent refresh, and API calls.
projects/sample/src/main.ts - Quickstart demos · Minimal NgModule and standalone setups.
projects/quickstart-demo/src/main.ts - Documentation source and site
Connections 21
- Primary npm package → Angular module: exports
- Primary npm package → Standalone providers: exports
- AuthConfig + DI registration → Angular module: configures
- AuthConfig + DI registration → Standalone providers: configures
- Angular module → OAuthService: provides
- Standalone providers → OAuthService: provides
- OAuthService → URL and callback parsing: builds and parses protocol data
- OAuthService → Identity provider: discovery, authorize, token, userinfo
- Identity provider → OAuthService: redirect callback and responses · Inputs require state, nonce, and configured validation checks.
- OAuthService → Token lifecycle: stores and refreshes tokens
- OAuthService → Validation handlers: validates responses
- Validation handlers → Hash handler: uses hashing
- JWKS package export → JWKS validation handler: exports
- JWKS validation handler → Validation handlers: optional implementation
- OAuthService → OAuth events: emits lifecycle events
- OAuth HTTP interceptor → OAuthService: gets access token
- OAuth HTTP interceptor → Resource-server hooks: delegates errors
- OAuth HTTP interceptor → Protected resource servers: authorized requests
- Full sample app → OAuthService: integrates
- Quickstart demos → Primary npm package: demonstrate usage
- Documentation source and site → Primary npm package: documents