Comprehensive Examples
Relevant source files
The following files were used as context for generating this wiki page:
The "Comprehensive Examples" suite provides a definitive reference for implementing the flext-auth library in real-world scenarios. These examples cover the entire library surface, ranging from basic user registration to advanced JWT operations, session management, and role-based access control (RBAC). They serve as functional documentation for the refactored clean architecture, demonstrating how components like identity_service, token_service, and session_service interact within the FlextAuth facade.
The suite is designed to showcase "REAL, working functionality" and follows the enterprise patterns defined in the project, such as the r (Result) pattern for error handling and the use of Pydantic-based settings and models.
Sources: examples/comprehensive_demo_03.py:1-12, examples/README.md:1-5, examples/refactored_system_showcase_04.py:1-10
Core Authentication Workflow
The primary entry point for most applications is the complete authentication lifecycle, which includes user registration, credential verification, and session initiation.
Lifecycle Sequence
The following diagram illustrates the standard flow from registration to session termination as implemented in the comprehensive demo.
The sequence above reflects the steps executed in the demo_complete_auth_workflow method.
Sources: examples/comprehensive_demo_03.py:23-45, examples/basic_usage_workflow.py:53-91
Key API Surface Methods
The following table summarizes the canonical API methods used across the examples:
| Method | Component | Description |
|---|---|---|
register_user | FlextAuth | Creates a new user identity with optional roles. |
authenticate_user | FlextAuth | Validates credentials and returns session/token data. |
create_token | FlextAuth | Generates a new JWT for a specific identity ID. |
validate_token | token_service | Verifies the integrity and expiration of a JWT. |
get_user | identity_service | Retrieves detailed identity information by ID. |
end_session_by_id | session_service | Terminates a specific active session. |
Sources: examples/README.md:7-18, examples/comprehensive_demo_03.py:28-44
Advanced Security & Operations
Role-Based Access Control (RBAC)
flext-auth supports multi-role assignments during registration. Examples demonstrate assigning both administrative and standard user roles to manage access levels.
# Advanced registration with multiple roles
register_result = auth.register_user(
username="admin_user",
email="admin@company.com",
password=password,
roles=["admin", "user"],
)
Sources: examples/basic_usage_workflow.py:24-31, examples/advanced_features_02.py:46-56
Session and Token Management
The library allows for fine-grained control over active sessions and JWT validation. The examples demonstrate handling multiple concurrent sessions for a single user and validating various token formats (e.g., Bearer tokens vs. raw strings).
Password Security Features
The demo_security_features and example_password_security sections demonstrate how the system handles varying password strengths. While the library facilitates secure hashing via bcrypt (referenced in pyproject.toml), the examples show validation of weak passwords and the generation of high-entropy credentials.
Sources: examples/comprehensive_demo_03.py:97-102, examples/advanced_features_02.py:80-97, pyproject.toml:23
System Architecture Integration
The refactored system emphasizes a "Clean Architecture" where the FlextAuth class acts as a simplified facade over complex internal services.
Component Relationship
Result Pattern Integration
The examples heavily utilize the r (or p.Result) pattern from flext-core. This ensures that every operation returns a structured object indicating success or failure, rather than throwing unhandled exceptions.
| Field | Type | Description |
|---|---|---|
success | bool | True if the operation completed as expected. |
failure | bool | True if an error occurred. |
value | T | The resulting data (Identity, Token, etc.) on success. |
error | str | Error message describing the failure. |
Sources: examples/refactored_system_showcase_04.py:44-48, examples/basic_usage_workflow.py:32-42
Summary
The comprehensive examples demonstrate that flext-auth is a robust, enterprise-ready authentication system. By providing a clear facade (FlextAuth) and structured result handling, the library enables developers to implement secure user lifecycles, advanced JWT validation, and RBAC with minimal boilerplate code. The inclusion of quick_start methods further simplifies initial deployment for projects with standard requirements.