# manfredsteyer/angular-oauth2-oidc architecture

> Architecture diagram of the GitHub repository manfredsteyer/angular-oauth2-oidc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manfredsteyer/angular-oauth2-oidc
- Repository: https://github.com/manfredsteyer/angular-oauth2-oidc

## Overview

#### 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: [`projects/lib/src/oauth-service.ts`](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/oauth-service.ts) (OAuthService), [`projects/lib/src/public_api.ts`](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/public_api.ts) (Primary npm package), [`projects/lib/src/interceptors/default-oauth.interceptor.ts`](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/interceptors/default-oauth.interceptor.ts) (OAuth HTTP interceptor), [`projects/lib/src/angular-oauth-oidc.module.ts`](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/angular-oauth-oidc.module.ts) (Angular module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumer["Consumer applications"]
  node_consumer_config["AuthConfig + DI registration<br/>integration contract<br/>[auth.config.ts]"]
end

subgraph group_core["Core OAuth library"]
  node_angular_module["Angular module<br/>NgModule integration"]
  node_standalone_providers["Standalone providers<br/>provider integration<br/>[provider.ts]"]
  node_public_api["Primary npm package<br/>package export<br/>[public_api.ts]"]
  node_oauth_service{{"OAuthService<br/>OAuth façade<br/>[oauth-service.ts]"}}
  node_oauth_events["OAuth events<br/>event stream<br/>[events.ts]"]
  node_token_lifecycle["Token lifecycle<br/>token management<br/>[tokens.ts]"]
  node_validation_contract["Validation handlers<br/>validation extension"]
  node_hash_handler["Hash handler<br/>crypto helper<br/>[hash-handler.ts]"]
  node_oauth_interceptor["OAuth HTTP interceptor<br/>HTTP boundary"]
  node_resource_hooks["Resource-server hooks<br/>HTTP error extension"]
end

subgraph group_protocol["Protocol and trust boundary"]
  node_protocol_helpers["URL and callback parsing<br/>protocol parser"]
  node_identity_provider{{"Identity provider<br/>external OAuth/OIDC endpoints"}}
  node_protected_apis{{"Protected resource servers<br/>external APIs"}}
end

subgraph group_optional["Optional validation package"]
  node_jwks_package["JWKS package export<br/>optional package<br/>[public-api.ts]"]
  node_jwks_handler["JWKS validation handler<br/>JWT signature validation"]
end

subgraph group_examples["Examples and docs"]
  node_full_sample["Full sample app<br/>Angular integration example<br/>[main.ts]"]
  node_quickstarts["Quickstart demos<br/>Angular integration examples<br/>[main.ts]"]
  node_documentation["Documentation source and site"]
end

node_public_api -->|"exports"| node_angular_module
node_public_api -->|"exports"| node_standalone_providers
node_consumer_config -->|"configures"| node_angular_module
node_consumer_config -->|"configures"| node_standalone_providers
node_angular_module -->|"provides"| node_oauth_service
node_standalone_providers -->|"provides"| node_oauth_service
node_oauth_service -->|"builds and parses protocol data"| node_protocol_helpers
node_oauth_service -->|"discovery, authorize, token, userinfo"| node_identity_provider
node_identity_provider -->|"redirect callback and responses"| node_oauth_service
node_oauth_service -->|"stores and refreshes tokens"| node_token_lifecycle
node_oauth_service -->|"validates responses"| node_validation_contract
node_validation_contract -->|"uses hashing"| node_hash_handler
node_jwks_package -->|"exports"| node_jwks_handler
node_jwks_handler -.->|"optional implementation"| node_validation_contract
node_oauth_service -->|"emits lifecycle events"| node_oauth_events
node_oauth_interceptor -->|"gets access token"| node_oauth_service
node_oauth_interceptor -->|"delegates errors"| node_resource_hooks
node_oauth_interceptor -->|"authorized requests"| node_protected_apis
node_full_sample -.->|"integrates"| node_oauth_service
node_quickstarts -.->|"demonstrate usage"| node_public_api
node_documentation -.->|"documents"| node_public_api

click node_consumer_config "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/auth.config.ts"
click node_angular_module "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/angular-oauth-oidc.module.ts"
click node_standalone_providers "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/provider.ts"
click node_public_api "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/public_api.ts"
click node_oauth_service "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/oauth-service.ts"
click node_oauth_events "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/events.ts"
click node_token_lifecycle "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/tokens.ts"
click node_validation_contract "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/token-validation/validation-handler.ts"
click node_hash_handler "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/token-validation/hash-handler.ts"
click node_oauth_interceptor "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/interceptors/default-oauth.interceptor.ts"
click node_resource_hooks "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/interceptors/resource-server-error-handler.ts"
click node_protocol_helpers "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/url-helper.service.ts"
click node_jwks_package "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/angular-oauth2-oidc-jwks/src/public-api.ts"
click node_jwks_handler "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/angular-oauth2-oidc-jwks/src/lib/jwks-validation-handler.ts"
click node_full_sample "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/sample/src/main.ts"
click node_quickstarts "https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/quickstart-demo/src/main.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_consumer_config toneBlue
class node_angular_module,node_standalone_providers,node_public_api,node_oauth_service,node_oauth_events,node_token_lifecycle,node_validation_contract,node_hash_handler,node_oauth_interceptor,node_resource_hooks toneAmber
class node_protocol_helpers,node_identity_provider,node_protected_apis toneMint
class node_jwks_package,node_jwks_handler toneRose
class node_full_sample,node_quickstarts,node_documentation toneIndigo
```

## Components

### Consumer applications

Applications own bootstrap, routing, and identity-provider registration.

- [AuthConfig + DI registration](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/auth.config.ts): integration contract · Configures issuer, client, redirect, scopes, flows, storage, validation, and resources. · `projects/lib/src/auth.config.ts`

### Core OAuth library

- [Angular module](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/angular-oauth-oidc.module.ts): NgModule integration · `projects/lib/src/angular-oauth-oidc.module.ts`
- [Standalone providers](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/provider.ts): provider integration · `projects/lib/src/provider.ts`
- [Primary npm package](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/public_api.ts): package export · `projects/lib/src/public_api.ts`
- [OAuthService](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/oauth-service.ts): OAuth façade · Coordinates login, callbacks, tokens, refresh, logout, and events. · `projects/lib/src/oauth-service.ts`
- [OAuth events](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/events.ts): event stream · `projects/lib/src/events.ts`
- [Token lifecycle](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/tokens.ts): token management · Models tokens, persistence, expiry, refresh scheduling, and silent refresh. · `projects/lib/src/tokens.ts`
- [Validation handlers](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/token-validation/validation-handler.ts): validation extension · Default validation is replaceable through DI or configuration. · `projects/lib/src/token-validation/validation-handler.ts`
- [Hash handler](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/token-validation/hash-handler.ts): crypto helper · `projects/lib/src/token-validation/hash-handler.ts`
- [OAuth HTTP interceptor](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/interceptors/default-oauth.interceptor.ts): HTTP boundary · Adds access tokens only for configured allowed URL prefixes. · `projects/lib/src/interceptors/default-oauth.interceptor.ts`
- [Resource-server hooks](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/interceptors/resource-server-error-handler.ts): HTTP error extension · `projects/lib/src/interceptors/resource-server-error-handler.ts`

### Protocol and trust boundary

- [URL and callback parsing](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/lib/src/url-helper.service.ts): protocol parser · Builds endpoint URLs and parses query or fragment callback values. · `projects/lib/src/url-helper.service.ts`
- **Identity provider**: external OAuth/OIDC endpoints · Discovery, authorization, token, userinfo, revocation, and logout services.
- **Protected resource servers**: external APIs

### Optional validation package

- [JWKS package export](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/angular-oauth2-oidc-jwks/src/public-api.ts): optional package · `projects/angular-oauth2-oidc-jwks/src/public-api.ts`
- [JWKS validation handler](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/angular-oauth2-oidc-jwks/src/lib/jwks-validation-handler.ts): JWT signature validation · 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](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/sample/src/main.ts): Angular integration example · Exercises configurations, guards, silent refresh, and API calls. · `projects/sample/src/main.ts`
- [Quickstart demos](https://github.com/manfredsteyer/angular-oauth2-oidc/blob/master/projects/quickstart-demo/src/main.ts): Angular integration examples · Minimal NgModule and standalone setups. · `projects/quickstart-demo/src/main.ts`
- **Documentation source and site**: documentation

## Connections

- 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
