Basic Auth and API Keys
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT Auth system provides a robust implementation for standard authentication methods, specifically Basic Authentication and API Keys. These methods serve as the primary entry points for identity verification before tokens are issued or sessions are established. Basic Auth relies on traditional username/password credentials, while API Key authentication facilitates stateless programmatic access.
Within the flext-auth ecosystem, these methods are categorized as ProviderTypes. They are integrated into a unified authentication facade that handles registration, credential verification, and security events like account lockouts.
Sources: src/flext_auth/history.json:96-121, examples/README.md:5-20
Authentication Architecture
The architecture follows a provider-based pattern where specific authentication methods are handled by dedicated logic but exposed through a centralized FlextAuth interface.
Provider Registration
Authentication methods are defined via the ProviderTypes enumeration. Both BASIC and APIKEY are first-class citizens in the provider registry. This allows the system to remain extensible while providing a consistent API for various credential types.
The diagram shows how the FlextAuth facade routes requests to specific providers based on the provided credentials.
Sources: src/flext_auth/history.json:104-121, examples/basic_usage_flows.py:84-110
Basic Authentication Workflow
Basic Authentication in FLEXT Auth centers on the authenticate_user method. It involves verifying a user's plain-text password against a stored hash (typically using Bcrypt).
Key Components
- Identity Manager: Retrieves user details by username.
- Password Service: Handles the hashing and verification logic using configured rounds.
- Security Events: Tracks
LOGIN_SUCCESSandLOGIN_FAILUREto enforce security policies.
Authentication Sequence
The following sequence outlines the typical flow for Basic Authentication:
API Key Authentication
API Key authentication is represented by the API and APIKEY constants. Unlike session-based auth, API keys are typically used for service-to-service communication or programmatic access where a long-lived or purpose-specific credential is required.
Configuration and Limits
API Keys are subject to specific validation limits defined in the system constants to prevent abuse and ensure security.
| Parameter | Default/Limit | Source |
|---|---|---|
MAX_TOKEN_LENGTH | 4096 characters | history.json:164 |
API_TOKEN_TYPE | "api" | history.json:101 |
MIN_TOKEN_LENGTH | 32 characters | history.json:231 |
Sources: src/flext_auth/history.json:101, src/flext_auth/history.json:164, src/flext_auth/history.json:231
Security and Validation
Both Basic Auth and API Keys are governed by strict security constants to mitigate brute-force attacks and ensure credential strength.
Credential Constraints
The system enforces minimum and maximum lengths for usernames and passwords to maintain database integrity and security standards.
| Component | Min Length | Max Length | Source |
|---|---|---|---|
| Username | 3 | 50 | history.json:206-208 |
| Password | 8 | 128 | history.json:215-217 |
| Secret Key | 32 | 4096 | history.json:182, 165 |
Lockout Mechanism
To protect Basic Auth from brute-force attempts, the system implements a lockout policy.
- Max Attempts: Defaults to 5 failed logins.
- Lockout Duration: Defaults to 15-30 minutes depending on configuration.
- Events: Triggers
ACCOUNT_LOCKEDerror codes.
Sources: src/flext_auth/history.json:204-222, src/flext_auth/history.json:236-250, examples/comprehensive_demo_03.py:90-100
Implementation Example
The following example demonstrates how a developer uses the FlextAuth facade to perform Basic Authentication, which implicitly uses the underlying providers.
from flext_auth import FlextAuth
# Initialize the service
auth = FlextAuth()
# Step 1: User registration (Basic Auth setup)
auth.register_user(
username="service_account",
email="service@example.com",
password="SecurePassword123!"
)
# Step 2: Authentication
result = auth.authenticate_user("service_account", "SecurePassword123!")
if result.success:
# result.value is an AuthIdentity containing the token and user info
token = result.value.token
Sources: examples/basic_usage_flows.py:105-130, examples/README.md:23-35
Conclusion
Basic Auth and API Keys form the foundational authentication layer of flext-auth. By leveraging the ProviderTypes.BASIC and ProviderTypes.APIKEY implementations, the system ensures that traditional user logins and programmatic access are handled with consistent security logic, strict validation, and integrated audit logging through security events.