Configuration Management - FeitianTech/postquantum-webauthn-platform GitHub Wiki

Configuration Management

Introduction
Configuration Architecture
Environment Variables
Configuration Categories
Storage Backend Configuration
Security Configuration
Feature Flags
Configuration Loading and Validation
Environment-Specific Configurations
Security Considerations
Troubleshooting
Best Practices

Introduction

The Post-Quantum WebAuthn Platform implements a sophisticated configuration management system that supports hierarchical configuration through environment variables and sensible defaults. The system is designed to handle diverse deployment scenarios while maintaining security and operational reliability across development, staging, and production environments.

The configuration system follows a layered approach where environment variables override default values, providing flexibility for different deployment contexts while ensuring secure defaults for production environments.

Configuration Architecture

The configuration system is built around a centralized configuration module that manages all application settings through environment variables and default values.

graph TB
subgraph "Configuration Layer 1: Environment Variables"
ENV1[FIDO_SERVER_SECRET_KEY]
ENV2[FIDO_SERVER_RP_ID]
ENV3[FIDO_SERVER_GCS_ENABLED]
ENV4[FIDO_SERVER_PQC_ENABLED]
end
subgraph "Configuration Layer 2: Default Values"
DEF1[Default RP Name: Demo server]
DEF2[Default RP ID: localhost]
DEF3[GCS Disabled: False]
DEF4[PQC Disabled: False]
end
subgraph "Configuration Layer 3: Runtime Resolution"
RES1[Secret Key Resolution]
RES2[RP ID Determination]
RES3[Storage Backend Selection]
RES4[Feature Flag Evaluation]
end
subgraph "Application Configuration"
APP1[Flask Application]
APP2[FIDO Server]
APP3[Storage Backends]
APP4[Security Policies]
end
ENV1 --> RES1
ENV2 --> RES2
ENV3 --> RES3
ENV4 --> RES4
DEF1 --> RES2
DEF2 --> RES2
DEF3 --> RES3
DEF4 --> RES4
RES1 --> APP1
RES2 --> APP2
RES3 --> APP3
RES4 --> APP4

Diagram sources

Section sources

Environment Variables

The configuration system uses a comprehensive set of environment variables prefixed with FIDO_SERVER_ to manage all aspects of the application configuration.

Core Configuration Variables

Variable	Description	Default Value	Environment
`FIDO_SERVER_SECRET_KEY`	Flask session secret as base64 string	Generated randomly	Production
`FIDO_SERVER_SECRET_KEY_FILE`	Path to session secret file	`instance/session-secret.key`	Production
`FIDO_SERVER_RP_NAME`	Relying Party display name	`"Demo server"`	All
`FIDO_SERVER_RP_ID`	Relying Party identifier	Auto-detected from hostname	All

Storage Configuration Variables

Variable	Description	Default Value	Environment
`FIDO_SERVER_GCS_ENABLED`	Enable Google Cloud Storage	`False` (disabled)	Production
`FIDO_SERVER_GCS_BUCKET`	Cloud storage bucket name	Required if GCS enabled	Production
`FIDO_SERVER_GCS_CREDENTIALS_FILE`	Path to service account JSON	None	Production
`FIDO_SERVER_GCS_CREDENTIALS_JSON`	Service account JSON content	None	Production
`FIDO_SERVER_GCS_PROJECT`	GCP project ID override	None	Production
`FIDO_SERVER_GCS_USER_FOLDER_PREFIX`	User data folder prefix	`"user-data"`	All
`FIDO_SERVER_GCS_USER_CREDENTIAL_SUBDIR`	Credential storage subdirectory	`"credentials"`	All

Security Configuration Variables

Variable	Description	Default Value	Environment
`FIDO_SERVER_TRUSTED_ATTESTATION_CA_SUBJECTS`	Trusted CA subject names	None	Production
`FIDO_SERVER_TRUSTED_ATTESTATION_CA_FINGERPRINTS`	Trusted CA fingerprint list	None	Production
`FIDO_SERVER_SESSION_METADATA_RECOVER`	Enable session metadata recovery	None	Production

Feature Configuration Variables

Variable	Description	Default Value	Environment
`FIDO_SERVER_SESSION_METADATA_RECOVER`	Enable session metadata recovery	None	All

Section sources

Configuration Categories

The configuration system organizes settings into distinct categories based on functionality and security requirements.

Server Settings Configuration

Server settings control fundamental application behavior including network binding, debugging, and basic operational parameters.

classDiagram
class ServerSettings {
+string host
+int port
+bool debug
+string secret_key
+validate_host() bool
+validate_port() bool
+generate_secret() bytes
}
class RPConfiguration {
+string rp_name
+string rp_id
+string rp_origin
+determine_rp_id() string
+build_rp_entity() RpEntity
}
class SecurityConfiguration {
+set~string~ trusted_ca_subjects
+set~string~ trusted_ca_fingerprints
+bool session_metadata_recover
+validate_security_settings() bool
}
ServerSettings --> RPConfiguration : "configures"
ServerSettings --> SecurityConfiguration : "secures"

Diagram sources

Security Policy Configuration

Security policies define trust relationships, attestation validation, and session management parameters.

flowchart TD
START([Security Configuration Load]) --> CHECK_CA["Check Trusted CA Subjects"]
CHECK_CA --> PARSE_SUBJECTS["Parse CA Subject List"]
PARSE_SUBJECTS --> VALIDATE_SUBJECTS{"Valid Subjects?"}
VALIDATE_SUBJECTS --> |Yes| CHECK_FINGERPRINTS["Check Trusted CA Fingerprints"]
VALIDATE_SUBJECTS --> |No| DEFAULT_SUBJECTS["Use Default Subjects"]
CHECK_FINGERPRINTS --> PARSE_FINGERPRINTS["Parse Fingerprint List"]
PARSE_FINGERPRINTS --> VALIDATE_FINGERPRINTS{"Valid Fingerprints?"}
VALIDATE_FINGERPRINTS --> |Yes| ENABLE_SECURITY["Enable Security Features"]
VALIDATE_FINGERPRINTS --> |No| DEFAULT_FINGERPRINTS["Use Default Fingerprints"]
DEFAULT_SUBJECTS --> ENABLE_SECURITY
DEFAULT_FINGERPRINTS --> ENABLE_SECURITY
ENABLE_SECURITY --> END([Security Configuration Complete])

Diagram sources

config.py

Section sources

config.py

Storage Backend Configuration

The system supports multiple storage backends with automatic selection based on configuration and availability.

Local Storage Configuration

Local storage is the default backend for development and testing environments, storing data in the filesystem.

sequenceDiagram
participant App as Application
participant Config as Configuration
participant Storage as Local Storage
participant FS as File System
App->>Config : Check storage backend
Config->>Config : Evaluate GCS_ENABLED flag
Config->>Storage : Initialize local backend
Storage->>FS : Create session directory
FS-->>Storage : Directory created
Storage-->>App : Local storage ready
Note over App,FS : Local storage operations
App->>Storage : Store credential
Storage->>FS : Write to file
FS-->>Storage : File written
Storage-->>App : Operation complete

Diagram sources

Google Cloud Storage Configuration

Cloud storage provides scalable, distributed storage for production deployments with automatic credential resolution.

sequenceDiagram
participant App as Application
participant GCS as GCS Module
participant Auth as Authentication
participant Bucket as Cloud Storage
App->>GCS : Check GCS enabled
GCS->>GCS : Parse FIDO_SERVER_GCS_ENABLED
GCS->>GCS : Check FIDO_SERVER_GCS_BUCKET
GCS->>Auth : Build client credentials
Auth->>Auth : Load service account JSON
Auth->>Bucket : Initialize client
Bucket-->>Auth : Client ready
Auth-->>GCS : Client authenticated
GCS-->>App : GCS ready for operations
Note over App,Bucket : GCS operations
App->>GCS : Upload credential
GCS->>Bucket : Store blob
Bucket-->>GCS : Blob stored
GCS-->>App : Operation complete

Diagram sources

Section sources

Security Configuration

Security configuration encompasses trust anchor management, attestation validation, and session security policies.

Trust Anchor Management

The system maintains configurable trust anchors for attestation validation with support for both subject-based and fingerprint-based verification.

Configuration Type	Environment Variable	Purpose	Validation
CA Subjects	`FIDO_SERVER_TRUSTED_ATTESTATION_CA_SUBJECTS`	Subject-based trust	Comma/newline-separated list
CA Fingerprints	`FIDO_SERVER_TRUSTED_ATTESTATION_CA_FINGERPRINTS`	Fingerprint-based trust	Hexadecimal values (≥40 chars)

Session Metadata Security

Session metadata security ensures proper isolation and protection of user session data with configurable cleanup policies.

stateDiagram-v2
[*] --> SessionCreated
SessionCreated --> Active : User activity
Active --> Inactive : Timeout period
Inactive --> Pruned : Cleanup interval
Pruned --> [*] : Data removed
Active --> Active : Touch last access
Inactive --> Active : New activity
note right of Pruned
Local cleanup : 14-day inactive age
Local cleanup : 6-hour interval
Cloud cleanup : On-demand
end note

Diagram sources

Section sources

Feature Flags

The platform implements several feature flags to enable/disable advanced capabilities based on deployment requirements and environment availability.

Post-Quantum Cryptography (PQC) Support

PQC support enables quantum-resistant cryptographic algorithms with runtime detection of available mechanisms.

flowchart TD
START([PQC Detection]) --> LOAD_OQS["Load OQS Bindings"]
LOAD_OQS --> CHECK_AVAILABILITY{"OQS Available?"}
CHECK_AVAILABILITY --> |No| ERROR_NO_OQS["Error: OQS not available"]
CHECK_AVAILABILITY --> |Yes| GET_MECHANISMS["Get Enabled Mechanisms"]
GET_MECHANISMS --> DETECT_AVAILABLE["Detect Available PQC Algorithms"]
DETECT_AVAILABLE --> COMPARE_LISTS{"All algorithms available?"}
COMPARE_LISTS --> |Yes| ENABLE_PQC["Enable PQC Features"]
COMPARE_LISTS --> |No| WARN_MISSING["Warn about missing algorithms"]
WARN_MISSING --> ENABLE_PQC
ENABLE_PQC --> LOG_SELECTION["Log algorithm selection"]
LOG_SELECTION --> END([PQC Ready])
ERROR_NO_OQS --> END

Diagram sources

pqc.py

Supported PQC Algorithms

Algorithm ID	Algorithm Name	Security Level	Use Case
`-50`	ML-DSA-87	Highest	Maximum security
`-49`	ML-DSA-65	High	Balanced security/performance
`-48`	ML-DSA-44	Medium	Lightweight deployment

Section sources

Configuration Loading and Validation

The configuration system implements comprehensive validation and error handling to ensure reliable application startup.

Secret Key Resolution

The secret key resolution process follows a hierarchical approach with fallback mechanisms for different deployment scenarios.

flowchart TD
START([Secret Key Resolution]) --> CHECK_ENV["Check FIDO_SERVER_SECRET_KEY"]
CHECK_ENV --> ENV_SET{"Environment variable set?"}
ENV_SET --> |Yes| USE_ENV["Use environment value"]
ENV_SET --> |No| CHECK_FILE["Check FIDO_SERVER_SECRET_KEY_FILE"]
CHECK_FILE --> FILE_SET{"File path set?"}
FILE_SET --> |Yes| READ_FILE["Read secret from file"]
FILE_SET --> |No| CHECK_STORED["Check stored secret"]
READ_FILE --> FILE_VALID{"File readable?"}
FILE_VALID --> |Yes| USE_FILE["Use file content"]
FILE_VALID --> |No| CHECK_STORED
CHECK_STORED --> STORED_FOUND{"Stored secret exists?"}
STORED_FOUND --> |Yes| USE_STORED["Use stored secret"]
STORED_FOUND --> |No| GENERATE["Generate new secret"]
GENERATE --> WRITE_FILE["Write to file"]
WRITE_FILE --> USE_NEW["Use new secret"]
USE_ENV --> VALIDATE["Validate secret"]
USE_FILE --> VALIDATE
USE_STORED --> VALIDATE
USE_NEW --> VALIDATE
VALIDATE --> SUCCESS([Secret Key Ready])

Diagram sources

config.py

Startup Validation

Startup validation ensures all critical dependencies are available before accepting requests.

sequenceDiagram
participant Startup as Startup Module
participant Metadata as Metadata Bootstrap
participant Storage as Storage Backend
participant Session as Session Store
Startup->>Metadata : Bootstrap FIDO metadata
Metadata-->>Startup : Metadata ready
Startup->>Storage : Verify cloud storage
Storage-->>Startup : Storage ready
Startup->>Session : Test session operations
Session->>Session : Create test session
Session->>Session : Touch last access
Session->>Session : List credentials
Session-->>Startup : Session ready
Startup->>Session : Clean up test session
Session-->>Startup : Cleanup complete
Startup-->>Startup : All dependencies verified

Diagram sources

startup.py

Section sources

Environment-Specific Configurations

The configuration system adapts to different deployment environments with appropriate defaults and security measures.

Development Environment

Development environments prioritize ease of setup and debugging with minimal security restrictions.

Setting	Development Value	Purpose
`FIDO_SERVER_GCS_ENABLED`	`False`	Disable cloud storage
`FIDO_SERVER_DEBUG`	`True`	Enable Flask debug mode
`FIDO_SERVER_SECRET_KEY`	Random generation	Development security
`FIDO_SERVER_RP_ID`	Auto-detected	Localhost binding

Production Environment

Production environments require strict security controls and cloud infrastructure integration.

Setting	Production Value	Purpose
`FIDO_SERVER_GCS_ENABLED`	`True`	Enable cloud storage
`FIDO_SERVER_SECRET_KEY`	Secure generation	Production security
`FIDO_SERVER_TRUSTED_ATTESTATION_CA_SUBJECTS`	Configured	Strict attestation
`FIDO_SERVER_SESSION_METADATA_RECOVER`	`True`	Enhanced reliability

Staging Environment

Staging environments mirror production with reduced security for testing purposes.

Setting	Staging Value	Purpose
`FIDO_SERVER_GCS_ENABLED`	`True`	Cloud storage enabled
`FIDO_SERVER_SECRET_KEY`	Secure generation	Production-like security
`FIDO_SERVER_TRUSTED_ATTESTATION_CA_SUBJECTS`	Limited set	Moderate security
`FIDO_SERVER_DEBUG`	`False`	Production-like behavior

Section sources

Security Considerations

The configuration system implements multiple security layers to protect sensitive data and ensure secure operations.

Sensitive Data Protection

Sensitive configuration data is protected through multiple mechanisms:

Secret Key Generation: Automatic generation of cryptographically secure secrets
File Permissions: Proper file system permissions for secret storage
Environment Isolation: Separate configuration for different environments
Encryption at Rest: Optional encryption for stored secrets

Secure Defaults

Production deployments automatically receive secure defaults:

# Secure default configuration examples
{
    "FIDO_SERVER_GCS_ENABLED": False,  # Prevent accidental cloud usage
    "FIDO_SERVER_DEBUG": False,        # Disable debug mode in production
    "SESSION_METADATA_RECOVER_ON_START": True,  # Enhanced reliability
    "TRUSTED_ATTESTATION_CA_SUBJECTS": None,    # Require explicit trust
}

Configuration Validation

All configuration values undergo validation to prevent security vulnerabilities:

Input Sanitization: Environment variable parsing with normalization
Type Checking: Runtime type validation for configuration values
Range Validation: Numeric values within acceptable ranges
Format Validation: String formats for certificates and keys

Section sources

Troubleshooting

Common configuration issues and their solutions are documented here for quick resolution.

Missing or Invalid Configuration

Problem: Application fails to start due to missing configuration Solution:

Verify all required environment variables are set
Check configuration syntax and format
Review application logs for specific error messages

Problem: GCS configuration fails Solution:

Verify FIDO_SERVER_GCS_BUCKET is set
Check service account credentials
Validate GCP project permissions

Storage Backend Issues

Problem: Local storage fails Solution:

Check directory permissions
Verify disk space availability
Ensure proper ownership

Problem: Cloud storage connection fails Solution:

Verify network connectivity
Check service account credentials
Validate bucket permissions

PQC Feature Issues

Problem: PQC algorithms not available Solution:

Install python-fido2-webauthn-test[pqc] extra
Verify liboqs installation
Check algorithm availability in OQS bindings

Session Metadata Problems

Problem: Session cleanup issues Solution:

Check cleanup intervals
Verify storage backend accessibility
Monitor disk space for local storage

Section sources

Best Practices