Authentication (Authn) & Sessions

Relevant source files

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

• src/forze_identity/authn/application/specs.py
• skills/forze-auth-tenancy-secrets/SKILL.md
• tests/unit/test_forze_fastapi/test_routes_authn.py
• pyproject.toml
• src/forze_identity/authn/orchestrator.py
• src/forze_identity/authn/domain/models/account.py
• src/forze_identity/authn/services/access_token.py

Authentication in the Forze framework is a multi-layered system designed to prove identity and establish sessions while maintaining strict isolation between domain logic and infrastructure. It follows a "verify-then-resolve" pipeline that decouples credential verification (vendor-specific) from principal resolution (vendor-agnostic), ensuring that internal systems only interact with canonical UUID-based identities.

The system handles various credential families including passwords, API keys, and tokens (JWT/OIDC). It is integrated deeply with the Forze execution context, allowing handlers to access identity information via the inv_ctx (invocation context) without manually parsing headers or managing session state.

Sources: skills/forze-auth-tenancy-secrets/SKILL.md:43-58, tests/unit/test_forze_fastapi/test_routes_authn.py:270-285

Architectural Overview

The authentication architecture is split into several distinct seams to support composability and external Identity Providers (IdPs).

The Verify-then-Resolve Pipeline

1. Verifiers: Implementations of PasswordVerifierPort, TokenVerifierPort, or ApiKeyVerifierPort. These prove the validity of a credential (e.g., checking a password hash or a JWT signature) and emit a VerifiedAssertion.
2. Resolvers: Implementations of PrincipalResolverPort. These take a VerifiedAssertion and translate it into a canonical AuthnIdentity, which includes a principal_id (UUID) and an optional tenant_id.
3. Orchestrator: The AuthnOrchestrator composes these components, gating calls based on the AuthnSpec and managing the high-level authentication flow.

The following diagram illustrates the flow from raw credentials to a bound identity in the execution context:

Core Components

Authn Specification (AuthnSpec)

The AuthnSpec defines the logical configuration for an authentication route, including enabled methods and the resource namespace.

Field	Description
name	Logical route identifier (e.g., "api", "internal").
enabled_methods	A frozenset of allowed methods (e.g., {"token", "password"}).
default_namespace	The resource namespace used for routing and identity resolution.

Sources: skills/forze-auth-tenancy-secrets/SKILL.md:71-74, tests/unit/test_forze_fastapi/test_routes_authn.py:24-27

Document Specifications

The identity plane relies on specific DocumentSpec instances to manage persistent state. These are marked as sensitive=True to prevent exposure in generated external surfaces like MCP tools.

• Password Account Spec: Manages PasswordAccount entities containing Argon2 hashes.
• API Key Account Spec: Manages ApiKeyAccount entities.
• Session Spec: Tracks active Session entities for token-based authentication.
• Identity Mapping Spec: Maps external subjects (from OIDC/IdPs) to internal UUIDs.

Sources: src/forze_identity/authn/application/specs.py:41-94

Authentication Flows

Token-Based Authentication & Refresh

The system supports JWT-based sessions with rotation. When a user logs in, they receive an access token and a refresh token. Using a refresh token rotates both tokens, and the previous refresh token is invalidated to prevent reuse (family revocation).

Password Reset Flow

The password reset flow is designed to be secure against user enumeration by returning a uniform 202 Accepted status regardless of whether the account exists.

1. Request: User submits a login identifier. If the user is known, an outbox event is staged with a reset token.
2. Confirm: User submits the reset token and a new password. This rotates the password and revokes all active sessions for that principal.

Sources: tests/unit/test_forze_fastapi/test_routes_authn.py:321-360

FastAPI Integration

Forze provides SecurityContextMiddleware to bind identity at the HTTP boundary.

app.add_middleware(
    SecurityContextMiddleware,
    ctx_dep=ctx_dep,
    authn=AuthnRequirement(
        ingress=(
            HeaderTokenAuthn(authn_spec=authn_spec, header_name="Authorization"),
            HeaderApiKeyAuthn(authn_spec=authn_spec, header_name="X-API-Key"),
        ),
    ),
    when_multiple_credentials="reject",
)

Sources: skills/forze-auth-tenancy-secrets/SKILL.md:83-93

Authentication Routes

attach_authn_routes generates a standard set of endpoints based on the AuthnKernelOp registry:

Path	Method	Description
/auth/login	POST	Authenticate and receive tokens.
/auth/refresh	POST	Rotate access/refresh tokens.
/auth/logout	POST	Invalidate current session.
/auth/change-password	POST	Update password for active principal.
/auth/password-reset/request	POST	Initiate reset flow (uniform response).
/auth/password-reset/confirm	POST	Complete reset with token.
/auth/api-keys	GET/POST	List or create self-service API keys.

Sources: tests/unit/test_forze_fastapi/test_routes_authn.py:31-43

External Identity Providers (OIDC)

Integration with external IdPs like Google or Firebase is handled via the TokenVerifierPort. Forze remains UUID-native; external subject strings are converted to canonical internal UUIDs via a PrincipalResolverPort.

• DeterministicUuidResolver: Generates a stable UUID based on the issuer and subject.
• MappingTableResolver: Uses a database table to link external subjects to manually or JIT-provisioned internal UUIDs.

Sources: skills/forze-auth-tenancy-secrets/SKILL.md:52-58, skills/forze-auth-tenancy-secrets/SKILL.md:126-140

Summary

The Authentication and Sessions module provides a robust, security-first implementation of identity management. By separating verification logic from principal resolution and enforcing UUID-native identities, it allows the application core to remain agnostic of specific authentication providers. The inclusion of session rotation, uniform password reset responses, and deep integration with the execution context ensures that developers can implement secure authentication with minimal boilerplate while adhering to hexagonal architecture principles.