# panva/openid-client architecture

> Architecture diagram of the GitHub repository panva/openid-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/panva/openid-client
- Repository: https://github.com/panva/openid-client

## Overview

openid-client is a JavaScript OAuth 2.0 and OpenID Connect client library. An application discovers an authorization server, builds an authorization request, receives the user’s redirect callback, exchanges the authorization response for tokens, and can then call protected resources. The API also supports other grant types, token and UserInfo operations, and JWT- and proof-of-possession-based extensions; Passport integration is a separate adapter. Most runtime capabilities are implemented in one large source file. Relationships shown here follow the README’s documented workflow and feature list; sampled source excerpts do not expose every implementation path.

Main entry points: [`src/index.ts`](https://github.com/panva/openid-client/blob/main/src/index.ts) (Code Grant & Callback), [`src/passport.ts`](https://github.com/panva/openid-client/blob/main/src/passport.ts) (Passport Strategy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_discovery["Discovery &amp; Registration<br/>[index.ts]"]
  node_extensions["OAuth/OIDC Extensions<br/>[index.ts]"]
end

subgraph group_flows["Authorization Flows"]
  node_authorization["Authorization Requests<br/>[index.ts]"]
  node_codegrant["Code Grant &amp; Callback<br/>[index.ts]"]
  node_othergrants["Other Grants<br/>[index.ts]"]
end

subgraph group_tokens["Token Operations"]
  node_tokens["Token Validation<br/>[index.ts]"]
  node_resourceops["Resource Requests<br/>[index.ts]"]
  node_tokenadmin["Introspection &amp; Revocation<br/>[index.ts]"]
end

subgraph group_adapters["Framework Adapters"]
  node_passport["Passport Strategy<br/>[passport.ts]"]
end

node_application(("Application"))
node_user(("End User"))
node_as["Authorization Server"]
node_resource["Protected Resource"]

node_application -->|"discovers server"| node_discovery
node_discovery -->|"fetches metadata"| node_as
node_application -->|"builds request"| node_authorization
node_authorization -->|"redirects user"| node_user
node_user -->|"authorizes at"| node_as
node_as -->|"redirects callback"| node_application
node_application -->|"exchanges callback"| node_codegrant
node_codegrant -->|"requests tokens"| node_as
node_application -->|"requests grant"| node_othergrants
node_othergrants -->|"requests tokens"| node_as
node_application -->|"requests resource"| node_resourceops
node_resourceops -->|"sends access token"| node_resource
node_application -->|"manages tokens"| node_tokenadmin
node_tokenadmin -->|"introspects or revokes"| node_as
node_application -->|"uses extensions"| node_extensions
node_extensions -->|"sends extended requests"| node_as
node_application -->|"uses strategy"| node_passport
node_passport -.->|"supports authentication flow"| node_codegrant

click node_discovery "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_authorization "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_codegrant "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_othergrants "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_tokens "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_resourceops "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_tokenadmin "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_extensions "https://github.com/panva/openid-client/blob/main/src/index.ts"
click node_passport "https://github.com/panva/openid-client/blob/main/src/passport.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_discovery,node_extensions,node_user toneBlue
class node_authorization,node_codegrant,node_othergrants toneAmber
class node_tokens,node_resourceops,node_tokenadmin,node_as toneMint
class node_passport toneRose
class node_application,node_resource toneIndigo
```

## Components

### Client API

- [Discovery & Registration](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`
- [OAuth/OIDC Extensions](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`

### Authorization Flows

- [Authorization Requests](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`
- [Code Grant & Callback](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`
- [Other Grants](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`

### Token Operations

- [Token Validation](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`
- [Resource Requests](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`
- [Introspection & Revocation](https://github.com/panva/openid-client/blob/main/src/index.ts): `src/index.ts`

### Framework Adapters

- [Passport Strategy](https://github.com/panva/openid-client/blob/main/src/passport.ts): `src/passport.ts`

### Other components

- **Application**
- **End User**
- **Authorization Server**
- **Protected Resource**

## Connections

- Application → Discovery & Registration: discovers server (evidence: `README.md`)
- Discovery & Registration → Authorization Server: fetches metadata (evidence: `README.md`)
- Application → Authorization Requests: builds request (evidence: `README.md`)
- Authorization Requests → End User: redirects user (evidence: `README.md`)
- End User → Authorization Server: authorizes at (evidence: `README.md`)
- Authorization Server → Application: redirects callback (evidence: `README.md`)
- Application → Code Grant & Callback: exchanges callback (evidence: `README.md`)
- Code Grant & Callback → Authorization Server: requests tokens (evidence: `README.md`)
- Application → Other Grants: requests grant (evidence: `README.md`)
- Other Grants → Authorization Server: requests tokens (evidence: `README.md`)
- Application → Resource Requests: requests resource (evidence: `README.md`)
- Resource Requests → Protected Resource: sends access token (evidence: `README.md`)
- Application → Introspection & Revocation: manages tokens (evidence: `README.md`)
- Introspection & Revocation → Authorization Server: introspects or revokes (evidence: `README.md`)
- Application → OAuth/OIDC Extensions: uses extensions (evidence: `README.md`)
- OAuth/OIDC Extensions → Authorization Server: sends extended requests (evidence: `README.md`)
- Application → Passport Strategy: uses strategy (evidence: `README.md`)
- Passport Strategy → Code Grant & Callback: supports authentication flow (evidence: `src/passport.ts`)
