# dexidp/dex architecture

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

- Interactive diagram: https://gitdiagram.com/dexidp/dex
- Repository: https://github.com/dexidp/dex

## Overview

##### Main Components
- External Clients: Represent the user-facing applications (such as web browsers, mobile apps, or other services) that authenticate using OpenID Connect. Label these as “Client Applications” or “OAuth2 / OIDC Clients.”
- Dex Core Service: This is the central component composed of the “cmd/dex” and “server” packages. It handles authentication flows, token issuance (ID tokens, refresh tokens), and acts as the gateway between clients and connectors.
- Web Interface: Depicted by the “web” directory, this component includes static assets (templates, CSS, images) and builds the user login and approval UI.
- Connectors Layer: Represented by the “connector” directory, which contains multiple submodules (LDAP, GitHub, SAML, etc.). These modules act as adapters to external identity providers. Indicate that each connector supports different protocols and features.
- Storage Backend: Show various storage modules from the “storage” directory (SQL, memory, etc.) that persist tokens, client configs, and session data. Note that Dex supports multiple storage options and uses configuration-driven strategies.
- API & Protobuf Interfaces: The “api” (and “api/v2”) directories contain protocol definitions (via protobuf) and gRPC services. These can be represented as a communication layer for programmatic interaction (e.g., between components or with clients that prefer gRPC).
- Configuration / Deployment: Additional files – like configuration YAML files, Docker Compose, Dockerfile, and Kubernetes manifests – indicate how Dex is deployed and configured. Optionally include a “Deployment/Config” cluster block to capture environment specifics.

##### Relationships and Data Flow
- From the “Dex Core Service,” illustrate connections to the “Connectors Layer” which in turn communicate with external identity providers (e.g., LDAP, GitHub, SAML, etc.).
- Optionally, illustrate the configuration/deployment layer and how it surrounds all components (for example, Dex running as a container managed by Kubernetes).

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize how Dex is organized into distinct packages that separate concerns (authentication logic, connectors, storage, API, and web presentation).
- Plugin-like Connector Architecture: Show that connectors are loosely coupled modules that can be added or removed based on operator configuration.
- Configuration-Driven: Note the use of YAML-based configuration files and environment variables (.envrc, config.yaml.dist) that control which connectors are enabled and tuning settings.
- Cloud Native & Containerization: Mention support for Kubernetes (with manifests and CRDs) and use of Docker for containerization.

##### Specific Technologies and Frameworks
- Language: Emphasize that the system is written in Go.
- Protocols: Include OpenID Connect, OAuth2 flows, and gRPC communication (via protobuf API definitions).
- Infrastructure: Reference Docker, Kubernetes, and Continuous Integration (evidenced by GitHub workflows and Docker Compose files).

- Clearly separate the external-facing layers (client interactions via the web login and API endpoints) from the internal processing layers (Dex core, connectors, storage).
- Client initiates authentication → Web UI (login page)
- Web UI forwards the request to Dex Core
- Dex Core invokes the appropriate Connector module to delegate authentication to the identity provider
- Results and tokens flow back from the Connector to the Dex Core, which in turn generates an ID Token that is sent back to the client.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("OAuth2/OIDC Clients"):::client
    B("Web UI (Login)"):::frontend
    C("Dex Core Service"):::core
    D("Connectors (GitHub, LDAP, SAML, etc.)"):::connectors
    E("Storage Backend"):::storage
    F("API & gRPC Interfaces"):::api
    G("External Identity Providers"):::idp
    H("Configuration/Deployment"):::deployment

    A -->|"authenticates"| B
    A -->|"authenticates"| C
    B -->|"forwards_request"| C
    C -->|"delegates_authentication"| D
    D <-->|"communicates_with"| G
    C <-->|"reads/writes"| E
    C -->|"exposes_gRPC_API"| F

    H ---|"configures"| B
    H ---|"configures"| C
    H ---|"configures"| D
    H ---|"configures"| E
    H ---|"configures"| F

    click C "https://github.com/dexidp/dex/blob/master/cmd/dex/main.go"
    click C "https://github.com/dexidp/dex/blob/master/server/server.go"
    click B "https://github.com/dexidp/dex/blob/master/web/web.go"
    click B "https://github.com/dexidp/dex/tree/master/web/templates/"
    click D "https://github.com/dexidp/dex/blob/master/connector/github/github.go"
    click D "https://github.com/dexidp/dex/blob/master/connector/ldap/ldap.go"
    click E "https://github.com/dexidp/dex/tree/master/storage/sql/"
    click E "https://github.com/dexidp/dex/tree/master/storage/memory/"
    click E "https://github.com/dexidp/dex/tree/master/storage/etcd/"
    click F "https://github.com/dexidp/dex/blob/master/api/api.proto"
    click F "https://github.com/dexidp/dex/blob/master/api/v2/api.proto"
    click H "https://github.com/dexidp/dex/blob/master/config.yaml.dist"
    click H "https://github.com/dexidp/dex/tree/master/Dockerfile"
    click H "https://github.com/dexidp/dex/blob/master/docker-compose.yaml"
    click H "https://github.com/dexidp/dex/tree/master/scripts/manifests/"

    class A client
    class B frontend
    class C core
    class D connectors
    class E storage
    class F api
    class G idp
    class H deployment

    classDef client fill:#f9e79f,stroke:#e67e22,stroke-width:2px,color:#000;
    classDef frontend fill:#aed6f1,stroke:#3498db,stroke-width:2px,color:#000;
    classDef core fill:#d5f5e3,stroke:#28b463,stroke-width:2px,color:#000;
    classDef connectors fill:#fadbd8,stroke:#e74c3c,stroke-width:2px,color:#000;
    classDef storage fill:#f5cba7,stroke:#e67e22,stroke-width:2px,color:#000;
    classDef api fill:#d6bcfa,stroke:#8e44ad,stroke-width:2px,color:#000;
    classDef idp fill:#f7dc6f,stroke:#f1c40f,stroke-width:2px,color:#000;
    classDef deployment fill:#f0b27a,stroke:#d35400,stroke-width:2px,color:#000;
```
