How mkhorasani/streamlit-authenticator works
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