# zitadel/oidc architecture

> Architecture diagram of the GitHub repository zitadel/oidc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zitadel/oidc
- Repository: https://github.com/zitadel/oidc

## Overview

##### Project type and purpose
- This is an OpenID Connect (OIDC) SDK for Go: a library/toolkit that provides both a Relying Party (RP/client) and an OpenID Provider (OP/server) implementation.
- It’s not a standalone app but a modular framework, with a rich set of example programs illustrating real-world usage.

##### File structure
- Top-level packages:
- pkg/client        → RP (relying party) and RS (resource server) code
- pkg/op            → OP (OpenID Provider) server code (endpoints, flows)
- pkg/oidc          → shared definitions & discovery logic
- pkg/crypto, pkg/http, pkg/strings → utility libraries
- example/           → runnable examples: client apps, resource servers, static & dynamic OP servers
- internal/          → test utilities (not part of public API)
- Configuration & CI: go.mod/sum, GitHub Actions, semantic-release, coverage & lint configs.

##### Key insights from the README
- Lists major package roles and supported OIDC/OAuth flows (code, PKCE, JWT profile, device auth, introspection, token exchange).
- Shows how examples wire up the SDK to real HTTP endpoints and HTML templates.
- Emphasizes semver, upgrade guide, certification goals.

##### Essential elements
- Storage interface boundary and example/server storage implementation.
- Detail pkg/client’s rp and rs modules, including JWT profile and introspection clients.
- Protocol steps (OAuth2 grant types, PKCE, device flow) where relevant.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    browser["End-User (Browser)"]:::external
    extIDP["External Identity Provider"]:::external
    resourceServer["Other Resource Server"]:::external

    %% Core SDK Modules
    subgraph "Core SDK Modules"
        direction TB
        clientCore["pkg/client/client.go"]:::core
        rp["pkg/client/rp"]:::core
        rs["pkg/client/rs"]:::core
        tokenexchange["Token Exchange Client"]:::core
        crypto["pkg/crypto"]:::utility
        httpUtil["pkg/http"]:::utility
        subgraph "pkg/oidc"
            direction TB
            discovery["discovery.go"]:::core
            codechallenge["code_challenge.go"]:::core
            deviceAuth["device_authorization.go"]:::core
            tokenTypes["token.go / introspection.go"]:::core
            jwtProfile["jwt_profile.go"]:::core
        end
    end

    %% OP Provider Modules
    subgraph "OP Provider (pkg/op)"
        direction TB
        opCore["pkg/op/op.go"]:::core
        opConfig["config.go / context.go"]:::core
        opDiscovery["discovery.go"]:::core
        opAuth["auth_request.go / endpoint.go"]:::core
        opToken["token_request.go / token_code.go / token_refresh.go / token_client_credentials.go / token_exchange.go / device.go"]:::core
        opIntrospect["token_intospection.go"]:::core
        opRevoke["token_revocation.go"]:::core
        opUserinfo["userinfo.go"]:::core
        opSession["session.go"]:::core
        storageIf["storage.go"]:::storage
        mockStorage["mock/storage.mock.go / storage.mock.impl.go"]:::storage
    end

    %% Example Applications
    subgraph "Example Applications"
        direction TB
        exClientApp["example/client/app/app.go"]:::example
        exClientAPI["example/client/api/api.go"]:::example
        exDevice["example/client/device/device.go"]:::example
        exGitHub["example/client/github/github.go"]:::example
        exService["example/client/service/service.go"]:::example
        exStaticOP["example/server/exampleop/op.go / templates"]:::example
        exDynamicOP["example/server/dynamic/op.go / login.go"]:::example
        exServerMain["example/server/main.go"]:::example
        exServerStorage["example/server/storage/storage.go"]:::example
    end

    %% Data Flows & Dependencies
    rp -->|"uses Discovery"| opDiscovery
    rp -->|"auth request via Browser"| opAuth
    browser -->|"visits Auth Endpoint"| opAuth
    opAuth -->|"issue auth code"| browser
    browser -->|"returns code"| rp
    rp -->|"token request"| opToken
    opToken -->|"token response"| rp
    rp -->|"verify token via JWT Profile"| jwtProfile
    rs -->|"introspection request"| opIntrospect
    opCore -->|implements| storageIf
    exServerStorage -.->|implements| storageIf
    opCore -->|uses| crypto
    opCore -->|uses| httpUtil
    clientCore -->|depends on| oidc
    rp -->|part of| clientCore
    rs -->|part of| clientCore
    tokenexchange -->|part of| clientCore

    %% Examples using SDK
    exClientApp -->|imports| clientCore
    exClientAPI -->|imports RP / RS| clientCore
    exDevice -->|imports Device Flow| oidc
    exGitHub -->|imports| clientCore
    exService -->|imports Service-to-Service| clientCore
    exStaticOP -->|uses OP SDK| opCore
    exDynamicOP -->|uses OP SDK| opCore
    exServerMain -->|boots| exStaticOP & exDynamicOP

    %% External
    extIDP -->|fed auth| opAuth
    resourceServer -->|protected by RS| rs

    %% Click Events
    click rp "https://github.com/zitadel/oidc/tree/main/pkg/client/rp"
    click rs "https://github.com/zitadel/oidc/tree/main/pkg/client/rs"
    click tokenexchange "https://github.com/zitadel/oidc/blob/main/pkg/client/tokenexchange/tokenexchange.go"
    click clientCore "https://github.com/zitadel/oidc/blob/main/pkg/client/client.go"
    click oidc "https://github.com/zitadel/oidc/tree/main/pkg/oidc"
    click codechallenge "https://github.com/zitadel/oidc/blob/main/pkg/oidc/code_challenge.go"
    click deviceAuth "https://github.com/zitadel/oidc/blob/main/pkg/oidc/device_authorization.go"
    click tokenTypes "https://github.com/zitadel/oidc/blob/main/pkg/oidc/token.go"
    click tokenTypes "https://github.com/zitadel/oidc/blob/main/pkg/oidc/introspection.go"
    click jwtProfile "https://github.com/zitadel/oidc/blob/main/pkg/oidc/jwt_profile.go"
    click discovery "https://github.com/zitadel/oidc/blob/main/pkg/oidc/discovery.go"
    click opCore "https://github.com/zitadel/oidc/blob/main/pkg/op/op.go"
    click opConfig "https://github.com/zitadel/oidc/blob/main/pkg/op/config.go"
    click opConfig "https://github.com/zitadel/oidc/blob/main/pkg/op/context.go"
    click opDiscovery "https://github.com/zitadel/oidc/blob/main/pkg/op/discovery.go"
    click opAuth "https://github.com/zitadel/oidc/blob/main/pkg/op/auth_request.go"
    click opAuth "https://github.com/zitadel/oidc/blob/main/pkg/op/endpoint.go"
    click opToken1 "https://github.com/zitadel/oidc/blob/main/pkg/op/token_request.go"
    click opToken2 "https://github.com/zitadel/oidc/blob/main/pkg/op/token_code.go"
    click opToken3 "https://github.com/zitadel/oidc/blob/main/pkg/op/token_refresh.go"
    click opToken4 "https://github.com/zitadel/oidc/blob/main/pkg/op/token_client_credentials.go"
    click opToken5 "https://github.com/zitadel/oidc/blob/main/pkg/op/token_exchange.go"
    click opToken6 "https://github.com/zitadel/oidc/blob/main/pkg/op/device.go"
    click opIntrospect "https://github.com/zitadel/oidc/blob/main/pkg/op/token_intospection.go"
    click opRevoke "https://github.com/zitadel/oidc/blob/main/pkg/op/token_revocation.go"
    click opUserinfo "https://github.com/zitadel/oidc/blob/main/pkg/op/userinfo.go"
    click opSession "https://github.com/zitadel/oidc/blob/main/pkg/op/session.go"
    click storageIf "https://github.com/zitadel/oidc/blob/main/pkg/op/storage.go"
    click mockStorage "https://github.com/zitadel/oidc/blob/main/pkg/op/mock/storage.mock.go"
    click mockStorageimpl "https://github.com/zitadel/oidc/blob/main/pkg/op/mock/storage.mock.impl.go"
    click exClientApp "https://github.com/zitadel/oidc/blob/main/example/client/app/app.go"
    click exClientAPI "https://github.com/zitadel/oidc/blob/main/example/client/api/api.go"
    click exDevice "https://github.com/zitadel/oidc/blob/main/example/client/device/device.go"
    click exGitHub "https://github.com/zitadel/oidc/blob/main/example/client/github/github.go"
    click exService "https://github.com/zitadel/oidc/blob/main/example/client/service/service.go"
    click exStaticOP "https://github.com/zitadel/oidc/blob/main/example/server/exampleop/op.go"
    click exStaticTemplates "https://github.com/zitadel/oidc/tree/main/example/server/exampleop/templates"
    click exDynamicOP "https://github.com/zitadel/oidc/blob/main/example/server/dynamic/op.go"
    click exDynamicLogin "https://github.com/zitadel/oidc/blob/main/example/server/dynamic/login.go"
    click exServerMain "https://github.com/zitadel/oidc/blob/main/example/server/main.go"
    click exServerStorage "https://github.com/zitadel/oidc/blob/main/example/server/storage/storage.go"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085
    classDef example fill:#ccffcc,stroke:#155724
    classDef external fill:#e0e0e0,stroke:#6c757d
    classDef storage fill:#ffe0b3,stroke:#856404
    classDef utility fill:#f0f0f0,stroke:#343a40
```
