# mkhorasani/streamlit-authenticator architecture

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

- Interactive diagram: https://gitdiagram.com/mkhorasani/streamlit-authenticator
- Repository: https://github.com/mkhorasani/streamlit-authenticator

## Overview

##### Project type and purpose
- This is a Python library distributed via PyPI that provides a secure authentication module (“streamlit-authenticator”) for Streamlit applications.
- It implements an MVC-style pattern (controllers, models, views, utilities) to handle user login, registration, password management, cookies, OAuth2 guest logins, and optional two-factor authentication via an external cloud API.

##### File-structure analysis
- Top-level:
- config.yaml – user credentials and settings (cookie, OAuth2, API key)
- setup.py, requirements.txt – packaging and dependencies
- docs/ – Sphinx documentation
- streamlit_authenticator/ – main package
- tests/ – test suite
- streamlit_authenticator/ components:
- controllers/ – AuthenticationController, CookieController
- models/ – AuthenticationModel, CookieModel, CloudModel, OAuth2 models (Google, Microsoft)
- views/ – AuthenticationView (Streamlit widgets)
- utilities/ – encryptor, hasher, validator, helpers, exceptions
- params.py – default widget parameters

##### Key insights from README
- The library is used by importing into a Streamlit app, loading config.yaml, creating an Authenticate object, and invoking widget methods (login, logout, register_user, etc.).
- Supports both username/password and OAuth2 guest logins, with optional two-factor codes via a cloud service (requires an API key).
- Widgets update the in-memory credentials dict and then re-dump config.yaml to persist changes.

##### Main components
A. Streamlit Application (Client UI)
B. streamlit_authenticator Library
1. Views (Streamlit widgets)
2. Controllers (login/logout logic, cookie management)
3. Models
- AuthenticationModel – verify credentials, hash passwords
- CookieModel – build/verify re-auth cookie
- CloudModel – send 2FA codes, reset password emails
- OAuth2 Models – handle Google/Microsoft flows
4. Utilities – hashing, encryption, validation, helpers, exception handling
5. Config Manager – load/dump config.yaml
C. Data Stores
- config.yaml (YAML file on disk)
- Browser cookie (client)
- Streamlit session_state (in-memory session)
D. External Services
- OAuth2 Providers (Google, Microsoft)
- Cloud API (email/2FA service)

##### Relationships & data flow
1. Streamlit app calls a View (e.g., login widget).
2. View invokes Controller (AuthenticationController) with user input.
3. Controller consults AuthenticationModel and Utilities (Hasher, Validator) to check credentials against config.yaml data (loaded by Config Manager).
4. On success: Controller writes session_state, issues a signed cookie via CookieController/CookieModel, and optionally calls CloudModel (to send 2FA code or reset email).
5. For OAuth2: View triggers OAuth2Model, opens browser redirect to provider, receives callback, maps guest user data into credentials, writes to config.yaml.
6. All updates to credentials are persisted by Config Manager dumping to config.yaml.

##### Architectural patterns & principles
- MVC (Views → Controllers → Models)
- Separation of concerns: UI, business logic, data access, utilities
- Modular packaging: each component in its own sub-package
- Config-driven behavior: all parameters in config.yaml
- Extensibility points: custom Validator injection, callback hooks on widgets

##### Essential elements
- Module names and their groupings (controllers, models, views, utilities)
- Data stores and their formats (YAML file vs. in-memory vs. client cookie)
- External dependencies (OAuth2, cloud email/2FA)
- Flow of control and data at each major step

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes and subgraphs

    %% Streamlit Application
    StreamlitApp["Streamlit Application (Client UI)"]:::frontend
    click StreamlitApp "https://github.com/mkhorasani/streamlit-authenticator/blob/main/tests/app.py"

    %% Library Package
    subgraph "streamlit_authenticator Library"
        direction TB

        subgraph "Views"
            direction TB
            AuthenticationView["AuthenticationView (Streamlit widgets)"]:::internal
            click AuthenticationView "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/views/authentication_view.py"
        end

        subgraph "Controllers"
            direction TB
            AuthController["AuthenticationController"]:::internal
            CookieController["CookieController"]:::internal
            click AuthController "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/controllers/authentication_controller.py"
            click CookieController "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/controllers/cookie_controller.py"
        end

        subgraph "Models"
            direction TB
            AuthModel["AuthenticationModel"]:::internal
            CookieModel["CookieModel"]:::internal
            CloudModel["CloudModel"]:::internal
            GoogleModel["Google OAuth2Model"]:::internal
            MicrosoftModel["Microsoft OAuth2Model"]:::internal
            click AuthModel "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/models/authentication_model.py"
            click CookieModel "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/models/cookie_model.py"
            click CloudModel "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/models/cloud/cloud_model.py"
            click GoogleModel "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/models/oauth2/google_model.py"
            click MicrosoftModel "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/models/oauth2/microsoft_model.py"
        end

        subgraph "Utilities"
            direction TB
            Encryptor["Encryptor"]:::internal
            Hasher["Hasher"]:::internal
            Validator["Validator"]:::internal
            Helpers["Helpers"]:::internal
            Exceptions["Exceptions"]:::internal
            click Encryptor "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/utilities/encryptor.py"
            click Hasher "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/utilities/hasher.py"
            click Validator "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/utilities/validator.py"
            click Helpers "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/utilities/helpers.py"
            click Exceptions "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/utilities/exceptions.py"
        end

        ConfigManager["Config Manager"]:::internal
        click ConfigManager "https://github.com/mkhorasani/streamlit-authenticator/blob/main/config.yaml"
        Params["Parameters (params.py)"]:::internal
        click Params "https://github.com/mkhorasani/streamlit-authenticator/blob/main/streamlit_authenticator/params.py"
    end

    %% Data stores
    ConfigFile["config.yaml (YAML file on disk)"]:::datastore
    BrowserCookie["Browser Cookie"]:::datastore
    SessionState["Streamlit session_state (in-memory)"]:::datastore

    %% External services
    OAuth2Providers["OAuth2 Providers\n(Google, Microsoft)"]:::external
    CloudAPI["Cloud API (Email/2FA service)"]:::external

    %% Connections
    StreamlitApp -->|"calls widget"| AuthenticationView
    AuthenticationView -->|"invoke login/logout"| AuthController
    AuthController -->|"verify credentials"| AuthModel
    AuthModel -->|"uses hasher/validator"| Hasher
    AuthModel -->|"reads/writes"| ConfigManager
    ConfigManager -->|"load/dump config"| ConfigFile

    AuthController -->|"issue cookie"| CookieController
    CookieController -->|"build/verify"| CookieModel
    CookieModel -->|"set cookie"| BrowserCookie

    AuthController -->|"write session"| SessionState

    AuthController -->|"send 2FA or reset"| CloudModel
    CloudModel -->|"API call"| CloudAPI

    AuthenticationView -->|"OAuth2 login"| GoogleModel
    AuthenticationView -->|"OAuth2 login"| MicrosoftModel
    GoogleModel -->|"redirect/callback"| OAuth2Providers
    MicrosoftModel -->|"redirect/callback"| OAuth2Providers
    GoogleModel -->|"persist guest"| ConfigManager
    MicrosoftModel -->|"persist guest"| ConfigManager

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef datastore fill:#fff9c4,stroke:#fdd835,color:#f57f17;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
```
