Auth Manager — Aquilia Documentation
Comprehensive guide and documentation for Auth Manager in the Aquilia framework. View API reference, examples, and implementation patterns.
Security & Auth AuthManager The AuthManager is the central coordinator for all authentication operations. It orchestrates identity verification, token issuance, password hashing, rate limiting, and session management. Architecture AuthManager Orchestration AuthManager Central Coordinator , , , , , ].map((b, i) => ( ))} OPERATIONS , , , , ].map((op, i) => ( ))} Constructor from aquilia.auth import ( AuthManager, RateLimiter, PasswordHasher, TokenManager, TokenConfig, KeyRing, KeyDescriptor, KeyAlgorithm, MemoryIdentityStore, MemoryCredentialStore, MemoryTokenStore, ) # 1. Stores identity_store = MemoryIdentityStore() credential_store = MemoryCredentialStore() token_store = MemoryTokenStore() # 2. Key ring (one active signing key) key = KeyDescriptor.generate(kid="k1", algorithm=KeyAlgorithm.RS256) key_ring = KeyRing(keys=[key]) # 3. Token manager token_manager = TokenManager( key_ring=key_ring, token_store=token_store, config=TokenConfig( issuer="my-app", audience=["api"], access_token_ttl=3600, # 1 hour refresh_token_ttl=2592000, # 30 days ), ) # 4. Auth manager auth = AuthManager( identity_store=identity_store, credential_store=credential_store, token_manager=token_manager, password_hasher=PasswordHasher(), # Argon2id (auto-fallback to PBKDF2) rate_limiter=RateLimiter( max_attempts=5, window_seconds=900, # 15 min window lockout_duration=3600, # 1 hour lockout ), ) Parameter Type Description ))} Password Authentication result = await auth.authenticate_password( username="alice@example.com", # looked up by email then username password="SuperSecret!23", scopes=["profile", "orders.read"], session_id=None, # auto-generated if omitted client_metadata= , ) # AuthResult fields result.identity # Identity object result.access_token # Signed JWT (header.payload.signature) result.refresh_token # Opaque rt_ result.session_id # sess_ result.expires_in # 3600 (seconds) Password Auth Flow , , , , , , ].map((step, i) => ( ))} API Key Authentication result = await auth.authenticate_api_key( api_key="ak_live_abc123def456...", required_scopes=["orders.read"], # optional scope enforcement ) # API key IS the token — no separate JWT issued result.access_token # == api_key result.refresh_token # None result.session_id # None result.metadata # Token Refresh # Refresh token rotation (security best practice) new_access, new_refresh = await auth.refresh_access_token( refresh_token="rt_old_token_here" ) # The old refresh token is REVOKED after use # This prevents replay attacks # Verify & decode an access token claims = await auth.verify_token(access_token) # TokenClaims(iss, sub, aud, exp, iat, nbf, jti, scopes, roles, sid, tenant_id) # Get identity directly from token identity = await auth.get_identity_from_token(access_token) # Returns None if token is invalid/expired Revocation & Logout # Revoke a single token await auth.revoke_token("rt_abc...", token_type="refresh") await auth.revoke_token(access_jwt, token_type="access") # extracts JTI # Logout — revoke everything for user or session await auth.logout(identity_id="user_42") await auth.logout(session_id="sess_abc123") Rate Limiter The built-in RateLimiter prevents brute-force password attacks with a sliding window and automatic lockout. from aquilia.auth import RateLimiter limiter = RateLimiter( max_attempts=5, # failures before lockout window_seconds=900, # 15-minute sliding window lockout_duration=3600, # 1-hour lockout ) # Record a failed attempt limiter.record_attempt("auth:password:alice@example.com") Parameter Default Description ))} Authentication Faults AuthManager raises structured Fault exceptions integrated with AquilaFaults. Fault Code When Raised ))} DI Integration AuthManager is available as a DI provider via AuthManagerProvider. All dependencies are resolved automatically. from aquilia.auth.integration.di_providers import ( AuthManagerProvider, IdentityStoreProvider, CredentialStoreProvider, ) )
Go to Homepage