Authentication Services
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Authentication Services within the flext-web project provide a standardized, typed interface for managing user identities, verifying credentials, and securing the web platform. The system is designed around the Railway-Oriented Programming pattern, ensuring that all authentication operations return structured result objects (p.Result) that explicitly handle success and failure states.
The service acts as a specialized layer within the broader FlextWebServices facade, exposing methods for user registration and credential validation. It integrates closely with the project's configuration system to manage security parameters such as secret keys and token expiration policies.
Sources: development.md, tests/unit/test_services.py:27-56, guides/configuration.md:96-104
Core Service Architecture
The authentication logic is encapsulated within service implementations that are accessed via a canonical public facade. This architecture ensures that operational code interacts with the web instance rather than internal service classes.
Authentication Flow
The following sequence diagram illustrates the typical flow for authenticating a user through the service layer.
The diagram represents the transition from a credential request to a structured result.
Sources: development.md, tests/unit/test_services.py:27-41
Key Functions and Operations
The authentication service supports two primary identity operations: verification of existing users and registration of new users.
User Authentication
The authenticate method validates provided credentials. In the testing environment, it is verified against canonical test credentials and ensures that the returned user_id matches the input username.
User Registration
The register_user method handles the creation of new user identities. It includes validation logic, such as rejecting numeric-only usernames, to maintain identity standards.
| Operation | Input Model | Success Criteria |
|---|---|---|
authenticate | WebAuthFixture.credentials | Returns user_id matching username |
register_user | m.Web.UserData | Returns created=True for valid strings |
Sources: tests/unit/test_services.py:27-56
Configuration and Security
Security parameters are managed through namespaced settings. These settings define the cryptographic algorithms and lifecycle policies for session tokens.
from flext_auth import FlextAuthSettings
settings = FlextAuthSettings(
secret_key="your-secret-key",
algorithm=c.Auth.Algorithms.HS256,
access_token_expire_minutes=30,
refresh_token_expire_days=7,
)
Sources: guides/configuration.md:96-104
Security Constraints
The project enforces strict type safety and validation for all authentication data. This includes:
- Username Validation: Rejection of numeric-only usernames during registration.
- Environment Variables: Use of the
FLEXT_prefix for configuring sensitive keys (e.g.,FLEXT_DATABASE_PASSWORD). - Result Pattern: Mandatory use of the
r(Result) pattern to avoid exception-based error handling in identity flows.
Sources: tests/unit/test_services.py:48-56, guides/configuration.md:129-132, pyproject.toml:135-155
Implementation Standards
Authentication services must adhere to the project's quality gates and architectural rules:
- Public API Rule: Operational code should prefer the
webfacade for authentication rather than direct service instantiation. - Type Safety: Every package must be validated for type safety; the
pyproject.tomlconfiguration includes specific plugins likepydantic.mypyto enforce this at the service boundary. - Service status: The status of the authentication-capable web service is monitored via
web.service_status(), ensuring capabilities likeflask_supportare active.
Sources: development.md, pyproject.toml:135-155, tests/unit/test_services.py:107-118
Summary
Authentication Services in flext-web provide a robust, result-oriented framework for identity management. By leveraging the canonical web facade and structured FlextAuthSettings, the system ensures that user verification and registration are handled with high type safety and consistent error reporting.