# zubir2k/cloudflare-oidc-broker architecture

> Architecture diagram of the GitHub repository zubir2k/cloudflare-oidc-broker, 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/zubir2k/cloudflare-oidc-broker
- Repository: https://github.com/zubir2k/cloudflare-oidc-broker

## Overview

Cloudflare OIDC Broker federates configured upstream identity providers and issues broker-controlled identities to downstream applications. The principal flow validates a client, stores short-lived authorization state, redirects to an upstream provider, checks the returned identity against per-client mappings and policy, then issues a broker code and signed tokens. D1 holds clients and mappings; KV holds ephemeral state. The Worker also exposes discovery, userinfo, revocation, logout, and administration. Relationships for unsampled endpoint logic are limited to those documented in the README; provider modules are grouped by their shared registry.

Main entry points: [`src/index.ts`](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/index.ts) (OIDC Worker), [`src/providers/registry.ts`](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/registry.ts) (Provider registry), [`src/providers/index.ts`](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/index.ts) (Provider loading), [`src/providers/google.ts`](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/google.ts) (Google provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_broker["OIDC broker"]
  node_worker["OIDC Worker<br/>[index.ts]"]
  node_d1[("D1 registry and mappings")]
  node_kv[("KV session state")]
  node_oidc["OIDC discovery and JWKS<br/>[oidc.ts]"]
  node_formpost["Authorization form response<br/>[formPost.ts]"]
  node_denied["Access denied page<br/>[errorPage.ts]"]
end

subgraph group_federation["Provider federation"]
  node_providerindex["Provider loading<br/>[index.ts]"]
  node_registry["Provider registry<br/>[registry.ts]"]
  node_google["Google provider<br/>[google.ts]"]
  node_github["GitHub provider<br/>[github.ts]"]
  node_microsoft["Microsoft provider<br/>[microsoft.ts]"]
  node_apple["Apple provider<br/>[apple.ts]"]
  node_discord["Discord provider<br/>[discord.ts]"]
  node_mydigitalid["MyDigital ID provider<br/>[mydigitalid.ts]"]
end

subgraph group_security["Identity security"]
  node_clientauth["Client credentials<br/>[clientAuth.ts]"]
  node_pkce["PKCE verification<br/>[pkce.ts]"]
  node_subhash["Isolated subject IDs<br/>[subHash.ts]"]
  node_jwt["Broker token signing<br/>[jwt.ts]"]
  node_access["Admin access check<br/>[access.ts]"]
  node_origin["Issuer origin<br/>[origin.ts]"]
end

subgraph group_admin["Administration"]
  node_adminconsole["Admin console<br/>[adminConsole.ts]"]
end

node_user(("User"))
node_application["Downstream application"]
node_idps["Upstream identity providers"]

node_user -->|"starts login"| node_application
node_application -->|"requests authorization"| node_worker
node_worker -->|"checks client and policy"| node_d1
node_worker -->|"stores transaction state"| node_kv
node_worker -->|"selects provider"| node_providerindex
node_providerindex -->|"exports lookup"| node_registry
node_registry -->|"creates provider"| node_google
node_registry -->|"creates provider"| node_github
node_registry -->|"creates provider"| node_microsoft
node_registry -->|"creates provider"| node_apple
node_registry -->|"creates provider"| node_discord
node_registry -->|"creates provider"| node_mydigitalid
node_google -.->|"authenticates upstream"| node_idps
node_github -.->|"authenticates upstream"| node_idps
node_microsoft -.->|"authenticates upstream"| node_idps
node_apple -->|"authenticates upstream"| node_idps
node_discord -.->|"authenticates upstream"| node_idps
node_mydigitalid -->|"exchanges code"| node_idps
node_idps -->|"returns callback"| node_worker
node_worker -->|"checks user mapping"| node_d1
node_worker -->|"stores broker code"| node_kv
node_worker -->|"returns broker code"| node_application
node_application -->|"exchanges code"| node_worker
node_worker -->|"verifies challenge"| node_pkce
node_worker -->|"parses credentials"| node_clientauth
node_worker -->|"derives subject"| node_subhash
node_worker -->|"mints ID token"| node_jwt
node_worker -->|"returns signed tokens"| node_application
node_worker -->|"serves discovery and keys"| node_oidc
node_worker -->|"resolves issuer"| node_origin
node_worker -->|"renders denied response"| node_denied
node_worker -->|"renders form response"| node_formpost
node_worker -->|"renders console"| node_adminconsole
node_worker -->|"verifies admin access"| node_access
node_adminconsole -->|"calls admin operations"| node_worker

click node_worker "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/index.ts"
click node_oidc "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/oidc.ts"
click node_clientauth "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/clientAuth.ts"
click node_pkce "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/pkce.ts"
click node_subhash "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/subHash.ts"
click node_jwt "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/jwt.ts"
click node_access "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/access.ts"
click node_origin "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/origin.ts"
click node_providerindex "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/index.ts"
click node_registry "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/registry.ts"
click node_google "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/google.ts"
click node_github "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/github.ts"
click node_microsoft "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/microsoft.ts"
click node_apple "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/apple.ts"
click node_discord "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/discord.ts"
click node_mydigitalid "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/mydigitalid.ts"
click node_adminconsole "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/views/adminConsole.ts"
click node_formpost "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/views/formPost.ts"
click node_denied "https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/views/errorPage.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_worker,node_d1,node_kv,node_oidc,node_formpost,node_denied,node_user toneBlue
class node_providerindex,node_registry,node_google,node_github,node_microsoft,node_apple,node_discord,node_mydigitalid toneAmber
class node_clientauth,node_pkce,node_subhash,node_jwt,node_access,node_origin toneMint
class node_adminconsole toneRose
class node_application,node_idps toneIndigo
```

## Components

### OIDC broker

- [OIDC Worker](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/index.ts): `src/index.ts`
- **D1 registry and mappings**
- **KV session state**
- [OIDC discovery and JWKS](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/oidc.ts): `src/utils/oidc.ts`
- [Authorization form response](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/views/formPost.ts): `src/views/formPost.ts`
- [Access denied page](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/views/errorPage.ts): `src/views/errorPage.ts`

### Provider federation

- [Provider loading](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/index.ts): `src/providers/index.ts`
- [Provider registry](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/registry.ts): `src/providers/registry.ts`
- [Google provider](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/google.ts): `src/providers/google.ts`
- [GitHub provider](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/github.ts): `src/providers/github.ts`
- [Microsoft provider](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/microsoft.ts): `src/providers/microsoft.ts`
- [Apple provider](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/apple.ts): `src/providers/apple.ts`
- [Discord provider](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/discord.ts): `src/providers/discord.ts`
- [MyDigital ID provider](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/providers/mydigitalid.ts): `src/providers/mydigitalid.ts`

### Identity security

- [Client credentials](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/clientAuth.ts): `src/utils/clientAuth.ts`
- [PKCE verification](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/pkce.ts): `src/utils/pkce.ts`
- [Isolated subject IDs](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/subHash.ts): `src/utils/subHash.ts`
- [Broker token signing](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/jwt.ts): `src/utils/jwt.ts`
- [Admin access check](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/access.ts): `src/utils/access.ts`
- [Issuer origin](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/utils/origin.ts): `src/utils/origin.ts`

### Administration

- [Admin console](https://github.com/zubir2k/cloudflare-oidc-broker/blob/main/src/views/adminConsole.ts): `src/views/adminConsole.ts`

### Other components

- **User**
- **Downstream application**
- **Upstream identity providers**

## Connections

- User → Downstream application: starts login (evidence: `README.md`)
- Downstream application → OIDC Worker: requests authorization (evidence: `README.md`)
- OIDC Worker → D1 registry and mappings: checks client and policy (evidence: `README.md`)
- OIDC Worker → KV session state: stores transaction state (evidence: `README.md`)
- OIDC Worker → Provider loading: selects provider (evidence: `src/index.ts`)
- Provider loading → Provider registry: exports lookup (evidence: `src/providers/index.ts`)
- Provider registry → Google provider: creates provider (evidence: `src/providers/google.ts`)
- Provider registry → GitHub provider: creates provider (evidence: `src/providers/github.ts`)
- Provider registry → Microsoft provider: creates provider (evidence: `src/providers/microsoft.ts`)
- Provider registry → Apple provider: creates provider (evidence: `src/providers/apple.ts`)
- Provider registry → Discord provider: creates provider (evidence: `src/providers/discord.ts`)
- Provider registry → MyDigital ID provider: creates provider (evidence: `src/providers/mydigitalid.ts`)
- Google provider → Upstream identity providers: authenticates upstream
- GitHub provider → Upstream identity providers: authenticates upstream
- Microsoft provider → Upstream identity providers: authenticates upstream
- Apple provider → Upstream identity providers: authenticates upstream (evidence: `src/providers/apple.ts`)
- Discord provider → Upstream identity providers: authenticates upstream
- MyDigital ID provider → Upstream identity providers: exchanges code (evidence: `src/providers/mydigitalid.ts`)
- Upstream identity providers → OIDC Worker: returns callback (evidence: `README.md`)
- OIDC Worker → D1 registry and mappings: checks user mapping (evidence: `README.md`)
- OIDC Worker → KV session state: stores broker code (evidence: `README.md`)
- OIDC Worker → Downstream application: returns broker code (evidence: `README.md`)
- Downstream application → OIDC Worker: exchanges code (evidence: `README.md`)
- OIDC Worker → PKCE verification: verifies challenge (evidence: `src/index.ts`)
- OIDC Worker → Client credentials: parses credentials (evidence: `src/index.ts`)
- OIDC Worker → Isolated subject IDs: derives subject (evidence: `src/index.ts`)
- OIDC Worker → Broker token signing: mints ID token (evidence: `src/index.ts`)
- OIDC Worker → Downstream application: returns signed tokens (evidence: `README.md`)
- OIDC Worker → OIDC discovery and JWKS: serves discovery and keys (evidence: `src/index.ts`)
- OIDC Worker → Issuer origin: resolves issuer (evidence: `src/index.ts`)
- OIDC Worker → Access denied page: renders denied response (evidence: `src/index.ts`)
- OIDC Worker → Authorization form response: renders form response (evidence: `src/index.ts`)
- OIDC Worker → Admin console: renders console (evidence: `src/index.ts`)
- OIDC Worker → Admin access check: verifies admin access (evidence: `src/index.ts`)
- Admin console → OIDC Worker: calls admin operations (evidence: `README.md`)
