Password & Secrets Management
Relevant source files
The following files were used as context for generating this wiki page:
Password & Secrets Management in the flext-db-oracle project provides a robust framework for handling sensitive credentials required for Oracle database integration. The system is designed to prevent accidental exposure of sensitive data during logging, serialization, or debugging while ensuring secure delivery to the underlying Oracle drivers.
This module utilizes enterprise-grade patterns, integrating with Pydantic for validation and following Clean Architecture principles to isolate credential handling within the infrastructure layer. It ensures that sensitive strings, such as database passwords, are wrapped in specialized containers that mask their values by default.
Sources: src/README.md:21-25, src/flext_db_oracle/_models/password.py
Core Architecture and Implementation
The architecture centers around specialized models and configuration classes that enforce strict boundaries between sensitive data and public application surfaces.
Sensitive Data Containers
The project implements a FlextDbOraclePassword model to encapsulate database credentials. This model is utilized within FlextDbOracleSettings to ensure that passwords are not treated as plain strings, which could be inadvertently leaked in logs or error messages.
Sources: tests/unit/test_coverage_baseline.py:61-66, src/README.md:22
Configuration Integration
Secrets are primarily managed via the FlextDbOracleSettings class. This class uses Pydantic validation to enforce the presence and format of credentials before they are used by the FlextDbOracleApi or FlextDbOracleServices.
Sources: src/README.md:22, tests/unit/test_api.py:53-59
The diagram illustrates the relationship between configuration settings, the specialized password container, and the high-level API.
Sources: tests/unit/test_api.py:53-59, tests/unit/test_coverage_baseline.py:61-66
Environment-Based Secrets Management
The system supports secure credential injection through environment variables, which is the preferred method for production environments to avoid hardcoding secrets in source code or configuration files.
Environment Mapping
The project uses a specific naming convention for environment variables, typically prefixed with FLEXT_TARGET_ORACLE_. These are automatically mapped to the FlextDbOracleSettings fields.
Sources: tests/unit/test_services.py:461-468, tests/README.md:144-152
| Environment Variable | Description | Security Level |
|---|---|---|
FLEXT_TARGET_ORACLE_USERNAME | The Oracle database user account | Standard |
FLEXT_TARGET_ORACLE_PASSWORD | The password for the specified user | Sensitive (Masked) |
FLEXT_TARGET_ORACLE_HOST | Database server address | Standard |
FLEXT_TARGET_ORACLE_SERVICE_NAME | Oracle Service Name or SID | Standard |
Sources: tests/unit/test_services.py:461-468, tests/README.md:144-152
Data Flow for Credentials
The flow of secrets begins with external input (environment variables, CLI prompts, or configuration objects) and ends at the oracledb driver connection.
Flow of secrets from ingestion to database driver, highlighting the secure boundary where data is encapsulated.
Sources: src/README.md:21-25, pyproject.toml:285-286, tests/unit/test_services.py:28-35
Validation and Error Handling
The project implements strict validation to ensure that secrets are provided and valid before attempting a connection. This prevents the leaking of partial connection strings in error traces.
Validation Gates
- Presence Check: The system validates that
usernameandpasswordare not empty during initialization. - Serialization Protection: The
to_dict()method inFlextDbOracleApiis explicitly designed to exclude or mask the password field when serializing settings for logging or monitoring.
Sources: tests/unit/test_api.py:84-106, tests/unit/test_services.py:441-458
def test_to_dict_complete_serialization_real(self) -> None:
"""Test complete dictionary serialization excludes raw password."""
result = self.api.to_dict()
config_dict = result["settings"]
tm.that(config_dict["username"], eq="test_user")
tm.that("password" not in config_dict, eq=True)
Example showing the enforcement of secret exclusion during API serialization.
Sources: tests/unit/test_api.py:84-106
Summary
Password and secrets management in flext-db-oracle is built on a foundation of secure encapsulation and strict validation. By using the FlextDbOraclePassword container and environment-based configuration, the project adheres to enterprise security standards, ensuring that sensitive Oracle credentials remain protected throughout the application lifecycle.
Sources: src/README.md:73-76, tests/README.md:200-205