Authentication & Authorization

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_oracle_wms/_utilities/auth.py
• tests/unit/test_authentication.py
• tests/unit/test_authentication_core.py
• src/flext_oracle_wms/README.md
• examples/03_complete_functionality_showcase.py
• tests/unit/oracle_wms_complete_discovery.py

Authentication and Authorization in the flext-oracle-wms library provide enterprise-grade security mechanisms for integrating with Oracle Warehouse Management System (WMS) Cloud. The system is designed to support multiple authentication protocols, ensuring secure communication between the FLEXT data integration platform and Oracle WMS REST APIs.

The module focuses on modularity and type-safety, utilizing the FlextResult (r pattern) for consistent error handling and Railway-Oriented Programming (ROP). It supports several industry-standard methods, primarily focusing on Basic Authentication and OAuth2, with architectural hooks for Bearer tokens and API Keys.
Sources: src/flext_oracle_wms/README.md:46-52, src/flext_oracle_wms/_utilities/auth.py:1-12

Authentication Architecture

The authentication system is built around the FlextOracleWmsUtilitiesAuth utility class and its nested Authenticator class. It separates configuration (settings) from execution (the authentication process), allowing for flexible credential management and header generation.

Core Authentication Flow

The following diagram illustrates the internal logic used by the Authenticator to generate valid security headers for API requests.

The authentication logic ensures that credentials are valid before performing encoding or token exchange. The get_auth_headers method acts as the primary interface for external clients to retrieve properly formatted HTTP headers.
Sources: src/flext_oracle_wms/_utilities/auth.py:15-62, tests/unit/test_authentication_core.py:108-140

Supported Authentication Methods

The system defines authentication methods through a centralized enumeration (OracleWMSAuthMethod), providing a standard set of supported protocols.

Method	Value	Implementation Status	Description
BASIC	basic	Fully Supported	Standard Base64 encoded username:password credentials.
OAUTH2	oauth2	Partially Supported	Architectural hooks present; requires client ID and secret.
BEARER	bearer	Placeholder	Reserved for token-based authentication.
API_KEY	api_key	Placeholder	Reserved for static key-based authentication.

Sources: tests/unit/test_authentication_core.py:21-35, src/flext_oracle_wms/_utilities/auth.py:32-51

Configuration and Settings

Authentication behavior is controlled via AuthSettings (typically found within the m.OracleWms namespace). This model validates business rules to ensure that the required credentials are provided for the selected method.

AuthSettings Attributes

• method: The authentication protocol (defaults to BASIC).
• username / password: Required for Basic Auth.
• oauth2_client_id / oauth2_client_secret: Required for OAuth2.
• oauth2_scope: Default scope set to wms.read wms.write.
• token_refresh_threshold: Time in seconds (default 300) to refresh tokens before expiry.

Validation Logic

The validate_business_rules() method ensures configuration integrity:

• If method is BASIC, both username and password must be present.
• If method is OAUTH2, both client_id and client_secret must be present.
  Sources: tests/unit/test_authentication_core.py:37-88, tests/unit/test_authentication.py:65-88

Implementation Details

Credential Encoding

For Basic Authentication, the library encodes credentials using base64. The formatted string is then prefixed with the Basic scheme in the Authorization header.

# Internal Basic Auth implementation
credentials = f"{self.settings.username}:{self.settings.password}".encode()
token = base64.b64encode(credentials).decode("ascii")
# Resulting Header: {"Authorization": "Basic <token>"}

Sources: src/flext_oracle_wms/_utilities/auth.py:36-43, src/flext_oracle_wms/_utilities/auth.py:59-62

Multi-Method Showcase

The library's examples demonstrate how to switch between different authentication settings using the Authenticator utility.

# Example of switching to Basic Auth
auth_config = m.OracleWms.AuthSettings(
    method=c.OracleWms.OracleWMSAuthMethod.BASIC,
    username=getattr(settings, "username", "invalid"),
    password=getattr(settings, "password", "invalid"),
)
auth_config.validate_business_rules()
authenticator = FlextOracleWmsAuthenticator(auth_config)
headers = authenticator.get_auth_headers()

Sources: examples/03_complete_functionality_showcase.py:118-126

Error Handling and Resilience

The authentication module utilizes the FLEXT r (result) pattern. Every authentication operation returns a p.Result, which explicitly indicates success or failure without raising unhandled exceptions during the flow.

Common failure scenarios handled include:

• Missing Credentials: Basic auth attempted without username/password.
• Unsupported Methods: Attempting to use bearer or api_key which are not yet implemented in the core logic.
• Unconfigured OAuth2: Attempting OAuth2 flow without the necessary underlying configuration.
  Sources: src/flext_oracle_wms/_utilities/auth.py:34-51, tests/unit/test_authentication_core.py:126-155

Conclusion

Authentication & Authorization in flext-oracle-wms provides a robust, settings-driven framework for securing Oracle WMS Cloud interactions. By centralizing logic in the Authenticator and enforcing strict validation through AuthSettings, the library ensures that enterprise integration remains secure, type-safe, and consistent with the broader FLEXT ecosystem.
Sources: src/flext_oracle_wms/README.md:104-125, src/flext_oracle_wms/_utilities/auth.py:15-62