# tomasvotava/fastapi-sso architecture

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

- Interactive diagram: https://gitdiagram.com/tomasvotava/fastapi-sso
- Repository: https://github.com/tomasvotava/fastapi-sso

## Overview

##### Project type and purpose
- Type: Python library / FastAPI plugin
- Purpose: Provide a unified SSO (OAuth2/OpenID Connect) abstraction for multiple identity providers (Google, Facebook, GitHub, Microsoft, etc.) that can be dropped into any FastAPI app.

##### File structure
- `fastapi_sso/` – the core package
– `sso/base.py` – defines the abstract base client and common flows
– `sso/<provider>.py` – concrete subclasses for each provider (Google, Facebook, etc.)
– `pkce.py` – implements PKCE code challenge & verifier logic
– `state.py` – session/state management (storing and verifying CSRF nonces)
- `examples/` – standalone scripts showing how to wire up the plugin in a FastAPI app
- `docs/` & `mkdocs.yml` – documentation generation
- `tests/` – unit tests covering providers, PKCE, base flows, race‐condition lock
- CI/CD configs – GitHub Actions workflows, code coverage, linting

##### Key architectural patterns
- Strategy pattern: each provider implements the same interface defined in `base.py`
- Context manager + async lock: ensures safe concurrent login flows
- Shared components: PKCE and state modules used by all providers
- Extensibility point: drop in a new `sso/<your_provider>.py`

##### Main components & relationships
+----------------+        +----------------------+       +----------------+
| FastAPI App &  |        | SSO Plugin Instance  |       | External IdP   |
|  HTTP Clients  | <----> | (fastapi_sso.SSO)    | <----> | (Google, FB…)  |
+----------------+        +----------------------+       +----------------+
|                           ^  ^   ^
|                           |  |   +-- PKCE module (code_challenge)
|                           |  +------ State module (nonce store, CSRF)
|                           +--------- Provider classes (Strategy subtypes)
|
v
+----------------+
|    Database    |  (optional session store for state)
+----------------+

- The FastAPI route handler calls into the SSO plugin
- The plugin orchestrates:
a. state generation & storage
b. PKCE challenge creation
c. redirect to provider’s auth endpoint
- After callback, plugin verifies state & PKCE, exchanges code for tokens, fetches user info
- Returns an OpenID/dict object back to your app

##### Details
- Extensibility: highlight how a new provider class plugs into `base.py`
- Concurrency safety: annotate the async‐lock on the context manager
- PKCE & state flows: call out these security modules as first‐class citizens
- Test coverage & CI pipelines can be noted in an “Auxiliary” section

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Consumer
    FastAPIApp["FastAPI App & HTTP Clients"]:::external

    %% SSO Plugin Core
    subgraph "SSO Plugin (fastapi_sso)" 
        direction TB
        SSOClass["Public Plugin API (SSO class)"]:::internal
        BaseClient["Abstract Base Client (base.py)"]:::internal
        PKCEModule["PKCE Module (pkce.py)"]:::internal
        StateModule["State Management (state.py)"]:::internal

        subgraph "Providers (Strategy subclasses)" 
            direction TB
            Google["Google Provider"]:::internal
            Facebook["Facebook Provider"]:::internal
            GitHub["GitHub Provider"]:::internal
            Microsoft["Microsoft Provider"]:::internal
            OtherProviders["Other Providers…"]:::internal
        end
    end

    %% Optional Database
    Database["Database (optional session store)"]:::external

    %% External Identity Providers
    subgraph "External Identity Providers"
        direction TB
        IdPs["Google, Facebook, GitHub, Microsoft, etc."]:::external
    end

    %% Examples, Docs, Tests, CI
    Examples["Examples (FastAPI wiring)"]:::dashed
    Docs["Documentation & mkdocs.yml"]:::dashed
    Tests["Unit Tests"]:::dashed
    CICD["CI/CD Configs"]:::dashed

    %% Connections
    FastAPIApp -->|"calls SSO methods"| SSOClass
    SSOClass -->|"uses interface"| BaseClient
    SSOClass -->|"uses"| PKCEModule
    SSOClass -->|"uses"| StateModule
    SSOClass -->|"selects provider"| Google
    SSOClass -->|"selects provider"| Facebook
    SSOClass -->|"selects provider"| GitHub
    SSOClass -->|"selects provider"| Microsoft
    SSOClass -->|"selects provider"| OtherProviders
    FastAPIApp -->|"optional state storage"| Database
    SSOClass -->|"redirect with code_challenge & state"| IdPs
    IdPs -->|"callback with code"| SSOClass
    SSOClass -->|"exchange code for tokens & fetch userinfo"| IdPs
    SSOClass -->|"returns user info dict"| FastAPIApp

    %% Context Lock Annotation
    SSOClass -. "async context manager + lock" .-> BaseClient

    %% Auxiliary Sections
    FastAPIApp --> Examples
    FastAPIApp --> Docs
    FastAPIApp --> Tests
    FastAPIApp --> CICD

    %% Click Events
    click BaseClient "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/sso/base.py"
    click Google "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/sso/google.py"
    click Facebook "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/sso/facebook.py"
    click GitHub "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/sso/github.py"
    click Microsoft "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/sso/microsoft.py"
    click OtherProviders "https://github.com/tomasvotava/fastapi-sso/tree/master/fastapi_sso/sso/"
    click PKCEModule "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/pkce.py"
    click StateModule "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/state.py"
    click SSOClass "https://github.com/tomasvotava/fastapi-sso/blob/master/fastapi_sso/__init__.py"
    click Examples "https://github.com/tomasvotava/fastapi-sso/tree/master/examples/"
    click Docs "https://github.com/tomasvotava/fastapi-sso/tree/master/docs/"
    click Tests "https://github.com/tomasvotava/fastapi-sso/tree/master/tests/"
    click CICD "https://github.com/tomasvotava/fastapi-sso/blob/master/.github/workflows/test.yml"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef external fill:#D5E8D4,stroke:#82B366,color:#82B366,stroke-width:1px
    classDef dashed stroke-dasharray: 5 5,fill:none,stroke:#AAAAAA,color:#555555
```
