# zalando/gin-oauth2 architecture

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

- Interactive diagram: https://gitdiagram.com/zalando/gin-oauth2
- Repository: https://github.com/zalando/gin-oauth2

## Overview

##### Main Components

a. Core Components:
- Gin-OAuth2 Middleware (Central Component)
- Authentication Providers:
- Zalando OAuth2
- Google OAuth2
- GitHub OAuth2
- Gin Framework Integration
- Session Management
- Access Control System

b. External Dependencies:
- Token Provider Service
- Token Info Service
- OAuth2 Provider Services (Google, GitHub, etc.)

##### Authorization Flow
**Client -> Gin Router -> Gin-OAuth2 Middleware -> OAuth2 Provider -> Token Validation -> Protected Resource**

##### Session Management Flow
**Client -> Login Handler -> OAuth2 Provider -> Callback -> Session Storage -> Protected Routes**

##### Access Control Flow
**Request -> Middleware -> Access Checker (UID/Team Based) -> Resource Access**

- Client Applications                                   |

- ↕

- Gin Framework                                        |

- Gin-OAuth2 Middleware                              |   |

- Auth Handlers|  | Session Manager|  | Access Control|  | Request Logger |    |   |

- ↕

- OAuth2 Provider Adapters                                   |

- Zalando OAuth2 |  | Google OAuth2  |  | GitHub OAuth2  |  | Custom OAuth2  |       |

- ↕

- External OAuth2 Services                                   |

- Google Auth   |  |  GitHub Auth   |  | Custom IdP     |                          |

##### Important Details

- Authentication flow paths
- Session management
- Access control mechanisms (UID-based and Team-based)
- Integration points with Gin framework
- Provider-specific configurations
- Security boundaries

##### Notes for Implementation

- Keep the abstraction level high enough to show the overall architecture but detailed enough to understand the authentication flows
- Middleware's pluggable nature with different OAuth2 providers
- Security boundaries clearly
- Error handling paths
- Document configuration requirements

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Applications"]
        CL[Browser/API Client]
    end

    subgraph GinFW["Gin Framework Layer"]
        GR[Router]
        subgraph GMW["Gin-OAuth2 Middleware"]
            direction TB
            AH["Auth Handlers"]:::core
            SM["Session Manager"]:::core
            AC["Access Control"]:::core
            RL["Request Logger"]:::logger
        end
    end

    subgraph Providers["OAuth2 Provider Adapters"]
        direction TB
        ZO["Zalando OAuth2"]:::provider
        GO["Google OAuth2"]:::provider
        GHO["GitHub OAuth2"]:::provider
        CO["Custom OAuth2"]:::provider
    end

    subgraph External["External OAuth2 Services"]
        direction TB
        GAS["Google Auth Service"]:::external
        GHAS["GitHub Auth Service"]:::external
        CIS["Custom IdP Service"]:::external
    end

    %% Flow Connections
    CL --> GR
    GR --> GMW
    AH --> ZO & GO & GHO & CO
    ZO --> CIS
    GO --> GAS
    GHO --> GHAS

    %% Component Relationships
    AH --> SM
    AH --> AC
    AH --> RL

    %% Styling
    classDef core fill:#2374ab,stroke:#000,stroke-width:2px,color:#fff
    classDef provider fill:#48a9a6,stroke:#000,stroke-width:2px,color:#fff
    classDef external fill:#757575,stroke:#000,stroke-width:2px,color:#fff
    classDef logger fill:#d4af37,stroke:#000,stroke-width:2px,color:#fff

    %% Click Events
    click GMW "https://github.com/zalando/gin-oauth2/blob/master/ginoauth2.go"
    click RL "https://github.com/zalando/gin-oauth2/blob/master/logging.go"
    click ZO "https://github.com/zalando/gin-oauth2/blob/master/zalando/zalando.go"
    click GO "https://github.com/zalando/gin-oauth2/blob/master/google/google.go"
    click GHO "https://github.com/zalando/gin-oauth2/blob/master/github/github.go"

    %% Legend
    subgraph Legend
        direction TB
        C1["Core Components"]:::core
        P1["Provider Adapters"]:::provider
        E1["External Services"]:::external
        L1["Logging System"]:::logger
    end
```
