SAML Provider
Relevant source files
The following files were used as context for generating this wiki page:
The SAML Provider is a core authentication component within the flext-auth ecosystem, designed to implement the SAML 2.0 protocol for enterprise Single Sign-On (SSO). It facilitates both Service Provider (SP)-initiated and Identity Provider (IdP)-initiated authentication flows, allowing the project to integrate with external identity management systems.
The provider is architected to handle metadata exchange, assertion validation, and signature verification. It adheres to the project's Railway-Oriented Programming (ROP) pattern by returning r[T] results for all operations, ensuring consistent error handling across the authentication stack.
Sources: src/flext_auth/providers/saml.py:1-12, README.md:10-15
Architecture and Design
The SAML Provider is implemented as FlextAuthSamlProvider, which inherits from FlextAuthProviderMixin and implements the p.Auth.FlextAuthBaseProvider protocol. This structure ensures that the SAML implementation is interchangeable with other provider types like JWT, LDAP, or OAuth2.
Component Relationship
The following diagram illustrates how the SAML provider fits into the broader provider ecosystem:
The diagram shows the inheritance from the base provider protocol and the inclusion of the provider mixin.
Sources: src/flext_auth/providers/saml.py:15-35
Core Functionality
The provider focuses on four primary business rules:
- SAML 2.0 Protocol Compliance: Implementing standard authentication flows.
- Metadata Management: Providing service provider configuration details for IdP trust.
- Assertion Validation: Verifying the integrity of SAML assertions and digital signatures.
- Attribute Mapping: Transforming SAML attributes into the internal
FlextAuthidentity model.
Provider Capabilities
The provider explicitly declares its supported operations, which are used for discovery within the flext-auth system.
| Capability | Description |
|---|---|
authenticate | Validates a SAML assertion and returns an authentication token. |
validate | Checks the validity of a specific SAML assertion token, including signature and expiry. |
metadata | Exposes provider details such as protocol version and capabilities. |
Sources: src/flext_auth/providers/saml.py:30-35, src/flext_auth/providers/saml.py:79-88
Implementation Logic
Authentication Flow
The authentication process involves receiving SAML assertion data (including signatures) and extracting identity information to generate a p.Auth.Token.
This flow represents the logic intended for the authenticate method to ensure secure identity extraction.
Sources: src/flext_auth/providers/saml.py:40-55
Metadata Configuration
The provider exposes metadata that identifies its configuration to the rest of the system. This is crucial for provider discovery and dynamic configuration.
def get_metadata(self) -> t.AttributeMapping:
return {
"name": "saml",
"version": "1.0.0",
"protocol": "SAML 2.0",
"capabilities": list(self.supports()),
"status": "basic_implementation",
}
Sources: src/flext_auth/providers/saml.py:57-75
Domain Integration
The SAML Provider uses constants and types defined in the core authentication module to ensure type safety and consistency.
| Constant Category | Referenced Type/Value | Purpose |
|---|---|---|
| Provider Type | ProviderTypes.SAML | Identifies the provider in the registry. |
| Protocol Version | SAML 2.0 | Defines the implementation standard. |
| Result Wrapper | r[T] | Standardized success/failure container. |
Sources: src/flext_auth/history.json:65-75, src/flext_auth/providers/saml.py:25-30
Testing and Quality Gates
As part of the flext-auth module, the SAML Provider is subject to strict quality gates defined in the project's test suite:
- Unit Testing: Isolated validation of the
FlextAuthSamlProvidermethods using mocks for external XML/Signature dependencies. - Integration Testing: Verification of the attribute mapping logic with the
AuthIdentitymodel. - Coverage: All provider implementations are required to contribute to the 95% minimum coverage threshold.
Sources: tests/README.md:20-45, pyproject.toml:115-125
Conclusion
The SAML Provider provides the foundation for enterprise-grade identity federation within flext-auth. While the current implementation serves as a "basic implementation," it establishes the necessary protocols for full SAML 2.0 assertion handling, metadata exchange, and attribute mapping, fully integrated into the project's Railway-Oriented architecture.