Authentication Module

Overview

The Authentication module provides comprehensive multi-factor authentication (MFA), multi-authentication strategy support, and session management for the banking platform. It handles user authentication, JWT token generation, credential management, and security policies.

API Prefix: /api/v1/auth

Route Verification Status

• Source Router: app/api/v1/endpoints/auth.py
• Live Route Count: 42
• Verification State: Verified (2026-06-28)
• Canonical Tracking: docs/API_ROUTE_DOCUMENTATION_TODO.md
• Verification Method: Route decorators extracted from @r.<method>(...) in app/api/v1/endpoints/auth.py.

Key Features

1. Multi-Authentication Strategies

• Local Authentication: Username/Email + Password with bcrypt hashing
• SAML 2.0: Enterprise Single Sign-On (SSO) integration
• LDAP: Directory services authentication (Active Directory, OpenLDAP)
• OAuth2/Social: Google and Azure integration (extensible)

2. Multi-Factor Authentication (MFA)

• TOTP (Time-based One-Time Password): Google Authenticator, Authy, Microsoft Authenticator
• SMS/Email OTP: One-time passwords via SMS or email
• Security Questions: Custom security question setup and verification
• Two-Factor Verification: Email/SMS based verification

3. Session Management

• User session tracking with last activity timestamp
• Multi-session support per user
• Session history audit trail
• Automatic session cleanup middleware
• Inactivity-based session termination

4. Token Management

• Access Tokens: JWT with 60-minute default expiry
• Refresh Tokens: Long-lived JWT for token refresh
• Reset Tokens: For password reset flows (10-minute expiry)
• Token Denylist: Redis-backed blacklist for immediate token revocation

5. Security Features

• Password encryption via Fernet (symmetric encryption)
• Password history tracking to prevent reuse
• Access policy validation (channel-based: Web, Mobile, USSD, Agent)
• Login attempt controls and rate limiting
• Geofencing restrictions for agent login
• IP-based access restrictions
• Device binding for operators
• Security headers and CORS protection

API Endpoints (Verified Against Live Router)

All paths below are effective paths under /api/v1/auth/*.

Core Authentication

POST /api/v1/auth/public_key
POST /api/v1/auth/refresh
POST /api/v1/auth/login
POST /api/v1/auth/validate
POST /api/v1/auth/validate/mobile
POST /api/v1/auth/login/ussd
POST /api/v1/auth/login/mobile
POST /api/v1/auth/agent/validate
POST /api/v1/auth/logout

MFA / 2FA

POST /api/v1/auth/2fa/request
POST /api/v1/auth/2fa/validate
POST /api/v1/auth/2fa/verify
POST /api/v1/auth/totp/verify
POST /api/v1/auth/reset/mfa
POST /api/v1/auth/reset/mfa/admin/approve
POST /api/v1/auth/reset/mfa/admin/reject
POST /api/v1/auth/reset/mfa/admin/pending

Security Questions

POST /api/v1/auth/security-questions/predefined
POST /api/v1/auth/security-questions/setup
POST /api/v1/auth/security-questions/verify
POST /api/v1/auth/security-questions
POST /api/v1/auth/security-questions/delete
POST /api/v1/auth/reset/security-questions

Credential / Secret Management

POST /api/v1/auth/password
POST /api/v1/auth/pin
POST /api/v1/auth/password/ussd
POST /api/v1/auth/reset/password
POST /api/v1/auth/reset/pin

LDAP

POST /api/v1/auth/ldap/login
POST /api/v1/auth/ldap/config

SAML

GET  /api/v1/auth/saml/metadata
POST /api/v1/auth/saml/metadata
POST /api/v1/auth/saml/login
POST /api/v1/auth/saml/acs
GET  /api/v1/auth/saml/exchange
GET  /api/v1/auth/saml/pending-2fa
POST /api/v1/auth/saml/config

Account Recovery / Reset Workflow

POST /api/v1/auth/reset/initiate
POST /api/v1/auth/reset/access-policy
POST /api/v1/auth/reset/verify-identity
POST /api/v1/auth/reset/status
POST /api/v1/auth/reset/cancel

Permission Dependency Notes (Verified)

Most authentication routes are governed by token/session validation logic, while specific administrative routes additionally enforce permission dependencies.

Confirmed explicit permission checks in auth.py include: - delete_security_question - approve_mfa_reset - reject_mfa_reset

Operational note: - Some configuration endpoints currently use permission_required("") and should be reviewed to ensure intended access control is explicit.

Standard Error Response Matrix

Use this error contract shape for auth flows:

{
  "status_code": 401,
  "error_code": "AUTH_ERROR",
  "message": "Human-readable summary",
  "details": {}
}

Common auth error mappings: - 400 -> malformed request payload or invalid reset flow state. - 401 -> invalid credentials, expired token, invalid OTP/TOTP. - 403 -> permission denied or policy restriction (IP/channel/device). - 404 -> identity/session/resource not found. - 409 -> conflicting auth state (for example duplicate or stale reset action). - 422 -> schema validation failure. - 429 -> too many attempts/rate limited. - 500 -> internal processing or integration error.

Database Models

Core Auth Models

• User: User account and profile information
• Credential: Encrypted password storage with salt
• CredentialHistory: Track password changes and prevent reuse
• UserSession: Active user sessions
• SessionHistory: Audit trail of all sessions
• UserSecurityQuestion: Security question setup per user
• UserSecurityAnswer: Answers to security questions
• BlackListedTokens: Revoked tokens (stored in Redis)
• UserIdentityProvider: Links users to external identity providers (SAML, LDAP)

Configuration Models

• SAMLConfig: SAML provider configuration (per tenant)
• LDAPConfig: LDAP directory configuration
• AccessPolicy: Channel-based access policies (Web, Mobile, USSD, Agent)
• LoginAttemptControl: Failed login attempt limits
• LoginFactor: Authentication factors required by policy
• PasswordRestriction: Password complexity requirements
• LoginIPRestriction: IP whitelist/blacklist
• LoginDayRestriction: Time-based login restrictions
• GeofencingRestriction: Location-based access control
• UserTOTPSecret: TOTP secrets for multi-factor auth

Authentication Flow

Local Login Flow

1. User submits username/email + password
2. System validates credentials against encrypted password
3. Access policy validation (channel, IP, device, time)
4. Login attempt tracking
5. If MFA enabled:
   a. Generate OTP/2FA challenge
   b. Send via SMS/Email/Push notification
   c. User verifies OTP
6. Generate JWT access token & refresh token
7. Create session record
8. Return tokens to client

SAML SSO Flow

1. User initiates login via SAML
2. System generates SAML AuthnRequest
3. Redirects to Identity Provider (IdP)
4. IdP authenticates user
5. IdP returns signed SAML Response
6. System validates signature & assertions
7. Creates/links user from SAML attributes
8. Applies access policy validation
9. If MFA enabled: 2FA challenge
10. Generate JWT tokens & session

LDAP Login Flow

1. User submits credentials
2. Connect to LDAP directory
3. Authenticate against directory
4. Retrieve user attributes from LDAP
5. Create/update local user record
6. Apply access policy validation
7. If MFA enabled: 2FA challenge
8. Generate JWT tokens & session

Multi-Factor Authentication Flow

1. Initial authentication succeeds
2. System checks MFA requirements for user/channel
3. If TOTP enabled: Validate TOTP token
4. If SMS/Email OTP: Generate & deliver OTP
5. User submits OTP
6. System validates OTP (time-limited, one-time use)
7. If Security Questions: Challenge random question
8. User provides answer
9. All factors validated: Issue tokens

Security Features

Password Security

• Bcrypt Hashing: Industry-standard password hashing with salt
• Encryption: Additional Fernet encryption for at-rest storage
• History: Track previous passwords, enforce no-reuse policy
• Expiration: Optional password expiry policies
• Complexity: Configurable requirements (length, uppercase, numbers, symbols)
• Reset: Secure password reset via email/SMS links (time-limited tokens)

Token Security

• JWT Signing: HS256 algorithm with secure secret
• Expiry: Configurable token lifetimes
• Refresh: Secure refresh token rotation
• Denylist: Redis-backed blacklist for immediate revocation
• Encryption: Token subject (username) encrypted with Fernet
• JTI Claims: Unique token ID for tracking

Access Control

• Channel-Based Policies: Different rules for Web/Mobile/USSD/Agent
• IP Restrictions: Whitelist/blacklist IP ranges
• Geofencing: Agent login restricted to store geofence
• Device Binding: Agents bound to specific devices
• Time Restrictions: Allow login only during business hours
• Login Attempt Control: Lock account after N failed attempts
• Inactivity Control: Auto-logout after N minutes of inactivity

Audit & Monitoring

• Access Logs: Every authentication attempt logged
• Session History: Track all user sessions with login/logout times
• Login Failures: Monitor and alert on suspicious patterns
• 2FA Challenges: Track which factors required/passed
• Credential Changes: Audit trail of password/PIN changes

Controllers & Business Logic

Key Controllers

• controller/auth.py: Core authentication logic
• authenticate_user(): Validate credentials
• check_two_factor(): Validate MFA requirements
• access_policy_validations(): Enforce access policies
• log_login_attempt(): Record login attempts

• change_user_password(): Secure password changes

• controller/multi_auth.py: Multi-authentication session manager

• Handle multiple auth strategies per user

• Session aggregation across auth methods

• controller/policy.py: Policy enforcement

• validate_login_factors(): Check required MFA factors
• get_login_factor_attempts(): Track failed attempts
• get_user_inactivity_control(): Session timeout policies

Configuration

Environment Variables

# JWT Configuration
ACCESS_TOKEN_EXPIRE_MINUTES=60
REFRESH_TOKEN_EXPIRE_MINUTES=10080  # 7 days
RESET_TOKEN_EXPIRE_MINUTES=10

# SAML Configuration
SAML_CONFIG_FILE=path/to/saml_config.json
SAML_DEBUG=false

# LDAP Configuration
LDAP_SERVER=ldap.example.com
LDAP_PORT=389

# MFA Configuration
TOTP_WINDOW=1  # Allow 1 time window before/after current
OTP_VALIDITY_MINUTES=5
MAX_LOGIN_ATTEMPTS=5
ACCOUNT_LOCKOUT_MINUTES=15

SAML Configuration Example

{
  "sp": {
    "entityId": "https://app.example.com/saml/metadata",
    "assertionConsumerService": {
      "url": "https://app.example.com/api/v1/auth/saml/acs"
    }
  },
  "idp": {
    "entityId": "https://idp.example.com/metadata",
    "singleSignOnService": {
      "url": "https://idp.example.com/sso"
    }
  }
}

Common Use Cases

1. User Registration & First Login

1. Admin creates user account
2. System sends temporary password via email/SMS
3. User logs in with temporary password
4. System forces password change
5. User sets up MFA (TOTP, Security Questions)
6. User completes login

2. Forgot Password Recovery

1. User clicks "Forgot Password"
2. System sends password reset link via email (expires in 10 min)
3. User clicks link
4. User enters new password
5. System validates password policy
6. Password updated, user can login

3. Device/Channel-Specific Access

1. User attempts login from new device
2. System checks device policy (might require additional verification)
3. If geofencing enabled: Validates device location
4. If first-time device: May require security questions
5. Access granted/denied based on policies

4. Session Timeout & Re-authentication

1. User inactive for configured duration (default 15 min)
2. System marks session as inactive
3. Next request requires re-authentication
4. User must login again (may trigger MFA)

Integration Points

External Services

• Email Service: Send password reset and OTP links
• SMS Gateway: Send SMS-based OTP/verification codes
• Firebase: Push notifications for 2FA challenges
• SAML IdP: Verify SAML assertions
• LDAP Directory: User lookup and authentication
• WebSocket: Real-time 2FA verification notifications

Internal Modules

• User Management: User provisioning and profile
• Policy Management: Access policy enforcement
• Notification: Multi-channel message delivery
• Audit Logging: Record access patterns
• Cache (Redis): Token denylist and session storage

Error Handling

Common Errors

• 401 Unauthorized: Invalid credentials or expired token
• 403 Forbidden: Insufficient permissions for resource
• 422 Validation Error: Invalid request payload
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error

MFA-Specific Errors

• 2FA_REQUIRED: User requires additional authentication
• OTP_EXPIRED: OTP token expired (typically 5 minutes)
• OTP_INVALID: Incorrect OTP or already used
• TOTP_INVALID: TOTP token invalid or outside time window
• MFA_SETUP_INCOMPLETE: User hasn't completed MFA setup

Testing

Test Categories

• Unit tests for password validation and encryption
• Integration tests for login flows
• SAML/LDAP endpoint mocking
• Token generation and validation
• Rate limiting and login attempt tracking
• Session management and cleanup

Test Files

• tests/test_auth.py: Core authentication tests
• tests/test_policy.py: Policy validation tests
• conftest.py: Test fixtures and mocking

Performance Considerations

1. Token Caching: Cache valid tokens to reduce database queries
2. User Lookup Optimization: Index on username/email for fast lookups
3. Session Cleanup: Background task to remove expired sessions
4. Redis Usage: Leverage Redis for token denylist and session storage
5. SAML Assertion Caching: Cache IdP metadata to reduce network calls

Security Best Practices

1. Always use HTTPS: Never send credentials over plaintext HTTP
2. Secure Token Storage: Store refresh tokens in HttpOnly cookies
3. CSRF Protection: Validate CSRF tokens on state-changing requests
4. Rate Limiting: Implement aggressive rate limiting on login endpoints
5. Audit Logging: Log all authentication events
6. MFA Enforcement: Require MFA for privileged accounts
7. Session Binding: Bind sessions to IP/Device fingerprint
8. Password Policy: Enforce strong, unique passwords

Troubleshooting

Common Issues

Issue	Cause	Solution
"Invalid Credentials"	Wrong password or user doesn't exist	Verify user exists and password is correct
Token Expired	Access token lifetime exceeded	Use refresh token to get new access token
2FA Not Working	TOTP/OTP misconfigured	Verify time sync on server and client device
SAML Login Fails	IdP metadata outdated or signature invalid	Refresh SAML metadata, verify certificate expiry
LDAP Connection Error	LDAP server unreachable	Check LDAP server connectivity and firewall
Session Timeout Too Aggressive	Inactivity policy set too low	Adjust inactivity timeout in policy configuration

Related Documentation

• Multi-Authentication System
• SAML Integration
• LDAP Integration
• Security Policies
• User Management