Security Values and Claims
Relevant source files
The following files were used as context for generating this wiki page:
The Security Values and Claims system in FLEXT Auth provides a standardized, type-safe framework for managing authentication metadata, token payloads, and security enforcement constraints. It centralizes the definition of JWT claims, validation regex patterns, and security thresholds to ensure consistency across the enterprise authentication service.
This system serves as the foundational layer for identity normalization, ensuring that claims from various providers (JWT, OAuth2, LDAP, Kerberos) are mapped into a unified internal representation. It defines critical limits for credentials, session lifecycles, and brute-force protection mechanisms.
Sources: src/flext_auth/_constants/auth_claims.py:1-12, src/flext_auth/history.json:115-125
Core Identity and Payload Claims
FLEXT Auth utilizes a prioritized set of claim keys to identify subjects and normalize contact information. This ensures that whether an identity is sourced internally or via an external provider like OAuth2, the system can reliably extract identifiers and display names.
The following diagram illustrates the claim normalization hierarchy used when processing tokens.
The system prioritizes specific keys for identity, naming, and contact information to maintain compatibility across different authentication protocols.
Sources: src/flext_auth/_constants/auth_claims.py:38-66
Standard Claim Keys
The system defines several "Final" string constants representing standard JWT and internal payload keys:
| Claim Key | Description | Priority/Usage |
|---|---|---|
sub | Subject claim key | Highest priority identity key |
identity_id | Internal identity identifier | Secondary identity key |
username | User login name | Fallback for identity and name |
name | Display name | Primary display name key |
email | User email address | Primary contact key |
roles | Roles list | List of assigned roles |
scope | OAuth scope | Permissions/Scope string |
Sources: src/flext_auth/_constants/auth_claims.py:44-59
Security Constraints and Validation
FLEXT Auth enforces strict validation limits for all security-relevant fields, including usernames, passwords, and tokens. These limits are centralized to prevent injection attacks and ensure system performance.
Credential Requirements
Passwords and usernames must adhere to specific length and complexity requirements to maintain a high security posture.
| Parameter | Minimum | Maximum | Default/Note |
|---|---|---|---|
| Username Length | 3 | 255 | Enforced via MAX_USERNAME_LENGTH |
| Password Length | 8 | 128 | Enforced via MIN_PASSWORD_LENGTH |
| Bcrypt Rounds | 4 | 31 | Default is 12 (DEFAULT_HASH_ROUNDS) |
| Secret Key Length | 32 | 4096 | Minimum required for cryptographic safety |
| Token Length | N/A | 4096 | Maximum size for JWT/Session strings |
Sources: src/flext_auth/_constants/auth_claims.py:101-118, src/flext_auth/_constants/auth_security.py:48-55
Brute Force and Lockout Policies
To protect against automated attacks, the system defines specific thresholds for login attempts and lockout durations.
The security model utilizes SECURITY_MAX_LOGIN_ATTEMPTS (5) and SECURITY_LOCKOUT_DURATION_MINUTES (15) as primary enforcement values.
Sources: src/flext_auth/_constants/auth_security.py:72-76, src/flext_auth/_constants/auth_claims.py:123-124
Token and Session Management
The system defines the lifecycle of authentication artifacts through specific expiry and rotation values. These apply to both JWT tokens and database-backed sessions.
Lifecycle Values
| Artifact | Default Expiry | Max Expiry |
|---|---|---|
| JWT Token | 30 Minutes | 1440 Minutes (24h) |
| Auth Session | 120 Minutes | 1440 Minutes (24h) |
| Max Sessions | 5 per user | N/A |
Sources: src/flext_auth/_constants/auth_security.py:11-13, src/flext_auth/_constants/auth_security.py:64-67
JWT Metadata
JWTs are generated and validated using standard claims defined within the Jwt and AuthSecurity constants:
- Algorithm: Defaulted to
HS256(HmacSHA256). - Issuer: Defaulted to
flext-auth. - Audience: Defaulted to
flext-auth-usersorflext-users. - Token Type: Defaulted to
Bearerfor use in Authorization headers.
Sources: src/flext_auth/_constants/auth_claims.py:119-121, src/flext_auth/_constants/auth_security.py:14-17
Domain Enumerations (Enums)
FLEXT Auth uses StrEnum types for type-safe validation of roles, permissions, and provider types. This ensures that only recognized security values are processed by the system.
class RoleTypes(StrEnum):
ADMIN = "admin"
USER = "user"
MODERATOR = "moderator"
GUEST = "guest"
class PermissionTypes(StrEnum):
READ = "read"
WRITE = "write"
DELETE = "delete"
ADMIN = "admin"
Sources: src/flext_auth/history.json:200-230, src/flext_auth/_constants/auth_claims.py:27-37
Implementation Example: Advanced Workflow
The following code snippet demonstrates how these security values and claims are utilized in a practical registration and validation flow, ensuring roles and tokens adhere to defined constants.
# From basic_usage_workflow.py
auth: FlextAuth = FlextAuth()
register_result = auth.register_user(
username="admin_user",
email="admin@company.com",
password="AdvancedPass123!",
roles=["admin", "user"], # Uses VALID_ROLE_TYPES
)
if register_result.success:
user_data = register_result.value
# Token operations utilize DEFAULT_JWT_ALGORITHM and expiry
token_validation = auth.token_service.validate_token(user_data.token)
Sources: examples/basic_usage_workflow.py:20-35, examples/advanced_features_02.py:100-115
Conclusion
The Security Values and Claims system centralizes authentication logic into a single source of truth. By defining immutable sets for VALID_TOKEN_TYPES, VALID_ROLE_TYPES, and specific PATTERN_EMAIL regex, FLEXT Auth ensures that every identity interaction within the platform is validated against rigorous enterprise security standards. This structure enables the system to maintain security across disparate providers while offering a consistent API for developers.