Auth and Identity Models

Relevant source files

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

• src/flext_auth/_models/auth_identity.py
• src/flext_auth/_models/auth_password.py
• src/flext_auth/_models/auth_response.py
• src/flext_auth/history.json
• src/flext_auth/_models/__init__.py
• examples/advanced_features_02.py

The Auth and Identity Models module provides the foundational data structures and logic for user representation, credential management, and authentication responses within the FLEXT Auth system. It defines how identities are structured, how passwords are securely handled, and how authentication results are communicated across the service.

The module is built on Pydantic-based entities and models, ensuring strict type validation and compatibility with the broader FLEXT API ecosystem. It handles the normalization of identity claims from various providers (OAuth, Kerberos) and enforces security invariants like account locking and credential verification.

Sources: src/flext_auth/_models/auth_identity.py, src/flext_auth/history.json:10-40

Core Identity Management

The AuthIdentity entity is the primary representation of a user or system actor. It extends the base m.Entity and includes fields for security state, contact information, and role-based access control.

Identity Structure and Fields

Identities are designed to be generic enough to support multiple authentication backends while maintaining strict validation for core fields like usernames and contact information.

Field	Type	Description	Constraints
name	str	Unique identity name	Min/Max length from constants
contact	str	Primary contact info (email)	Required
credential_hash	str	Hashed password string	Excluded from serialization
is_active	bool	Account activation status	Default: True
roles	t.StrSequence	List of assigned roles	Default: ["user"]
failed_attempts	int	Count of failed logins	Non-negative
locked_until	datetime	Lock expiration timestamp	Default: datetime.min

Sources: src/flext_auth/_models/auth_identity.py:17-57

Claim Normalization

The identity model includes a sophisticated normalization logic to map incoming claims from external providers (e.g., JWT payloads, OAuth tokens) into the standard FLEXT identity format.

The normalization process searches through defined candidate keys (e.g., sub, email, uid) to populate the name and contact fields if they are missing from the primary keys.

Sources: src/flext_auth/_models/auth_identity.py:61-125

Credential and Password Security

Security operations for credentials are encapsulated within the identity model but delegated to specialized utility classes for hashing and verification.

Password Utilities

The system utilizes PasswordUtil (typically a wrapper around Bcrypt) to handle sensitive credential operations. This ensures that plain-text passwords never persist within the identity entities.

def verify_credential(self, credential: str) -> p.Result[bool]:
    """Verify a credential against stored hash using bcrypt."""
    try:
        valid = FlextAuthModelsAuthPassword.PasswordUtil.verify_password(
            credential,
            self.credential_hash,
        )
        return r[bool].ok(valid)
    except c.EXC_BROAD_IO_TYPE as exc:
        return r[bool].fail_op("Credential verification", exc)

Sources: src/flext_auth/_models/auth_identity.py:141-150, src/flext_auth/_models/auth_password.py

Account Locking Logic

The identity model tracks authentication failures to mitigate brute-force attacks. An identity is considered locked if the current system time is less than the locked_until timestamp.

Sources: src/flext_auth/_models/auth_identity.py:127-131

Authentication Responses and Tokens

When authentication occurs, the system generates standardized response models containing identity information and security tokens.

Auth Identity Model (Response)

This model serves as the data transfer object (DTO) for successful authentication, combining the user identity with session-specific data.

Response Lifecycle

1. Request: An AuthIdentityRequest is submitted with raw credentials.
2. Verification: The system verifies the credentials against the stored hash in the AuthIdentity.
3. Response: On success, an AuthIdentity object is returned, populated with a token and session_id.

Sources: src/flext_auth/_models/auth_identity.py:133-157, src/flext_auth/_models/auth_response.py

Domain Constants and Limits

The behavior of these models is governed by a centralized set of constants defined in the FlextAuthConstants (aliased as c).

Constant Category	Description	Source
Auth.TokenTypes	Enumeration of supported tokens (access, refresh, api)	history.json:80
Auth.RoleTypes	Standard system roles (admin, user, guest)	history.json:115
Auth.Credentials	Length and complexity requirements for usernames/passwords	history.json:235
Auth.Security	Lockout durations and max login attempts	history.json:280

Sources: src/flext_auth/history.json:60-300

Conclusion

The Auth and Identity models provide a robust, type-safe framework for managing the lifecycle of a security identity. By decoupling credential hashing from the identity entity and providing a flexible claim normalization engine, the system remains compatible with diverse authentication sources while enforcing enterprise-grade security standards such as account lockout and Bcrypt-based verification.