JWT and Certificate Authentication

Relevant source files

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

• src/flext_auth/history.json
• examples/advanced_features_02.py
• examples/comprehensive_demo_03.py
• examples/basic_usage_workflow.py
• pyproject.toml
• tests/unit/README.md

JWT and Certificate Authentication are core components of the FLEXT Auth enterprise authentication and authorization service. These mechanisms provide secure, scalable, and type-safe identity verification for users and services within the platform.

The system utilizes JSON Web Tokens (JWT) for stateless session management and claim-based access control, while Certificate-based authentication offers robust security for machine-to-machine or high-security user interactions. These providers are integrated into a unified FlextAuth facade that orchestrates registration, authentication, and token validation workflows.

Sources: README.md:9-11, src/flext_auth/history.json:115-122, examples/advanced_features_02.py:19-21

JWT Authentication Architecture

The JWT implementation in FLEXT Auth is built on the pyjwt library and adheres to Pydantic 2 patterns for strict type validation. It supports various signing algorithms and implements automatic validation for claims such as issuer, audience, and expiration.

JWT Core Components

Component	Description
FlextJWTService	Infrastructure layer service responsible for token generation, signing, and verification.
TokenTypes	Enumeration of supported token categories: access, refresh, api, and bearer.
Algorithms	Supported cryptographic signing algorithms including HS256, RS256, and ES256.
JwtConfig	Configuration namespace for default expiry, issuer, and audience claims.

Sources: src/flext_auth/history.json:125-154, pyproject.toml:28, tests/unit/README.md:120-128

JWT Token Workflow

The following diagram illustrates the lifecycle of a JWT, from user authentication to service-side validation.

The workflow ensures that tokens are only issued after successful credential verification and are strictly validated against security constraints on every subsequent request.

Sources: examples/comprehensive_demo_03.py:35-50, src/flext_auth/history.json:368-380, tests/unit/README.md:214-224

Certificate Authentication

Certificate-based authentication is defined as a primary provider type within the FLEXT Auth architecture. It is designed for scenarios requiring high-assurance identity verification using X.509 certificates.

Configuration and Integration

Certificate authentication is grouped under the ProviderTypes enumeration, allowing it to be used interchangeably or alongside JWT and OAuth2 providers.

• Provider Key: certificate
• Dependency: Utilizes the cryptography library for handling certificate parsing and verification.
• Scope: Targeted at secure service-to-service communication and enterprise-grade user authentication.

Sources: src/flext_auth/history.json:141-154, pyproject.toml:23

Technical Configuration and Constants

The system defines strict validation limits and default values for authentication operations via the FlextAuthConstants class.

Default Security Parameters

Parameter	Default Value	Source
JWT Algorithm	HS256	src/flext_auth/history.json:200
JWT Expiry	30 Minutes	src/flext_auth/history.json:239
Max JWT Expiry	1440 Minutes (24h)	src/flext_auth/history.json:241
Min Secret Length	32 Characters	src/flext_auth/history.json:247
Issuer Claim	flext-auth	src/flext_auth/history.json:243
Audience Claim	flext-users	src/flext_auth/history.json:245

Implementation Snippet: JWT Configuration

The following pattern demonstrates how constants are organized using StrEnum for type-safe validation within the provider logic.

class Jwt:
    """JWT-specific constants for token generation and validation."""
    DEFAULT_ALGORITHM: Final[str] = "HS256"
    DEFAULT_EXPIRY_MINUTES: Final[int] = 30
    ISSUER_CLAIM: Final[str] = "flext-auth"
    AUDIENCE_CLAIM: Final[str] = "flext-users"
    DEFAULT_TOKEN_TYPE: Final[str] = "Bearer"

Sources: src/flext_auth/history.json:236-250

Validation and Error Handling

FLEXT Auth implements a comprehensive set of error codes to handle authentication failures in both JWT and Certificate-based flows.

Authentication Error Codes

• TOKEN_EXPIRED: The provided JWT has passed its exp claim time.
• INVALID_TOKEN: The token signature is invalid or the format is malformed.
• INVALID_CREDENTIALS: Initial authentication failed (e.g., certificate mismatch or wrong password).
• ACCOUNT_LOCKED: The user is currently under lockout due to security event thresholds.

Sources: src/flext_auth/history.json:332-342, tests/unit/README.md:214-224

Summary

JWT and Certificate Authentication provide the foundation for secure identity management in FLEXT Auth. By combining stateless JWTs for scalable application access with robust Certificate support for secure environments, the system ensures enterprise-grade security. The architecture emphasizes type-safety through Python 3.13 features like StrEnum and strict validation via infrastructure services.