Identity and Audit Service

Relevant source files

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

• src/flext_auth/services/identity_service.py
• src/flext_auth/services/_identity_audit.py
• src/flext_auth/history.json
• examples/basic_usage_workflow.py
• examples/comprehensive_demo_03.py
• tests/unit/README.md

Introduction

The Identity and Audit Service is a core component of the FLEXT Auth ecosystem, responsible for managing user identities, credential validation, and security auditing. It utilizes Railway-Oriented Programming (ROP) patterns to ensure robust error handling and predictable data flow across authentication and authorization workflows. The service acts as a facade for the underlying identity manager, orchestrating operations such as identity creation, credential rotation, and multi-factor verification while ensuring every significant security event is logged for audit purposes.

The service integrates closely with the FlextAuthSettings for security thresholds (like lockout durations and password complexity) and utilizes a dedicated dispatcher for event propagation. By combining identity management with an audit mixin, it provides a unified interface for both operational identity tasks and security compliance tracking.

Sources: src/flext_auth/services/identity_service.py:12-20, tests/unit/README.md:120-130

Architecture and Core Components

Service Structure

The service is implemented in FlextAuthIdentityService, which inherits from the base service class (s) and the FlextAuthIdentityAudit mixin. This architecture enforces a separation of concerns where the identity service handles business logic while the audit mixin manages security logging and telemetry.

The diagram shows the relationship between the Identity Service, its Audit mixin, and the underlying User Manager.
Sources: src/flext_auth/services/identity_service.py:12-32, src/flext_auth/services/_identity_audit.py

Key Classes and Responsibilities

Component	Description
FlextAuthIdentityService	The primary application service for managing identity lifecycles and authentication.
FlextAuthIdentityAudit	A specialized mixin that provides internal methods for logging security events and handling account lockout logic.
ServiceManagers	A container class injected during initialization that holds references to user_manager for data persistence.
AuthIdentityRequest	A Pydantic model used to validate input data during identity creation.

Sources: src/flext_auth/services/identity_service.py:12-40, src/flext_auth/history.json: "Writing file <constants.py>"

Identity Workflows

Authentication and Account Lockout

The authentication flow follows a strict "fail-fast" ROP pattern. It first checks for the existence of the identity, then validates if the account is currently locked before proceeding to credential verification. If verification fails, the service invokes the audit mixin to record the attempt and potentially increment lockout counters.

Flow of the authentication process including account lockout checks.
Sources: src/flext_auth/services/identity_service.py:42-63

Identity Creation

Creation involves normalization of contact info (e.g., lowercase email), validation against AuthIdentityRequest constraints, and secure credential hashing using PasswordUtil.

1. Validation: Ensures the name, contact, and credentials meet system requirements.
2. Hashing: Uses m.Auth.PasswordUtil.hash_password to transform plain text credentials into secure hashes.
3. Persistence: Calls the identity_manager.create_user method to store the new record.

Sources: src/flext_auth/services/identity_service.py:114-140, examples/basic_usage_workflow.py:17-30

Authorization and Auditing

The service provides a specialized authorize_identity method that checks for permissions within the identity's scope and immediately logs the result. This ensures that every authorization decision is recorded with its context (identity, permission, and resource).

Security Logging Methods

Internal audit methods are used to standardize security event reporting:

• _log_authorization_result: Records whether access to a resource was granted or denied.
• _handle_failed_attempt: Manages the state of failed login attempts and triggers lockouts when MAX_LOGIN_ATTEMPTS is reached.
• _log_success: Records successful sensitive operations like credential resets.

Sources: src/flext_auth/services/identity_service.py:73-85, src/flext_auth/services/_identity_audit.py, src/flext_auth/history.json: "Validation limits mapping"

Configuration and Constraints

The service behavior is governed by constants defined in FlextAuthConstants.Auth.

Constant	Value / Default	Description
CREDENTIAL_MIN_LENGTH	8	Minimum length for passwords during creation or reset.
MAX_LOGIN_ATTEMPTS	5	Threshold for account lockout.
LOCKOUT_DURATION_MINUTES	15 / 30	Duration an identity remains locked after failures.
BCRYPT_ROUNDS	12	Standard complexity for password hashing.

Sources: src/flext_auth/history.json: "class AuthSecurity", src/flext_auth/services/identity_service.py:100-105

Implementation Detail: Credential Management

The service supports both user-driven credential changes and administrative resets. Both operations validate the new credential against CREDENTIAL_MIN_LENGTH and log success via the audit layer.

def reset_credential(self, identity_id: str, new_credential: str) -> p.Result[bool]:
    """Railway-oriented credential reset for administrative operations."""
    identity_result = self.identity_manager.get_user(identity_id)
    if identity_result.failure:
        return r[bool].fail(identity_result.error)
    identity = identity_result.value
    if len(new_credential) < c.Auth.CREDENTIAL_MIN_LENGTH:
        return r[bool].fail(
            f"New credential must be at least {c.Auth.CREDENTIAL_MIN_LENGTH} characters long",
        )
    set_result = identity.update_credential(new_credential)
    if set_result.failure:
        return r[bool].fail(set_result.error)
    return r[bool].ok(
        self._log_success("Password reset successful", identity.name),
    )

Sources: src/flext_auth/services/identity_service.py:155-172

Summary

The Identity and Audit Service provides a secure, audited gateway for all identity-related operations in FLEXT Auth. By utilizing Railway-Oriented Programming and an integrated audit mixin, it ensures that authentication, authorization, and credential management are performed with consistent validation and comprehensive logging. This design facilitates both developer productivity through clear ROP results and organizational security through automated audit trails and lockout protections.