Account Lockout & Password Policy
Automatic account lockout after failed login attempts, configurable password complexity rules, and password history enforcement.
Account Lockout & Password Policy
FastCMS includes automatic account lockout protection against brute-force attacks and configurable password policies.
Account Lockout
After a configured number of consecutive failed login attempts, the account is automatically locked for a set duration.
Configuration
ACCOUNT_LOCKOUT_ENABLED=true
ACCOUNT_LOCKOUT_ATTEMPTS=5 # Failed attempts before lockout
ACCOUNT_LOCKOUT_DURATION=1800 # Lock duration in seconds (30 min)How It Works
- Each failed login increments the
failed_login_attemptscounter on the user - When the counter reaches
ACCOUNT_LOCKOUT_ATTEMPTS,locked_untilis set - Any login attempt while locked returns an error with remaining seconds
- A successful login resets the counter and clears
locked_until
Locked Account Response
HTTP/1.1 403 Forbidden{
"detail": "Account locked. Try again in 1742 seconds."
}Unlocking an Account (Admin)
Use the dedicated unlock endpoint:
curl -X POST http://localhost:8000/api/v1/admin/users/{user_id}/unlock \
-H "Authorization: Bearer ADMIN_TOKEN"This clears failed_login_attempts and removes locked_until, immediately restoring access.
Checking Lock Status (Admin)
curl http://localhost:8000/api/v1/admin/users/{user_id}/lock-status \
-H "Authorization: Bearer ADMIN_TOKEN"{
"user_id": "uuid",
"is_locked": true,
"failed_login_attempts": 5,
"locked_until": "2026-03-02T12:30:00Z",
"remaining_seconds": 847
}Password Policy
Enforce password complexity requirements at registration and password change.
Configuration
PASSWORD_MIN_LENGTH=8
PASSWORD_REQUIRE_UPPERCASE=true
PASSWORD_REQUIRE_LOWERCASE=true
PASSWORD_REQUIRE_DIGIT=true
PASSWORD_REQUIRE_SPECIAL=false
PASSWORD_HISTORY_COUNT=0 # 0 = disabled, N = remember last N passwordsValidation Response
When a password doesn't meet requirements:
HTTP/1.1 422 Unprocessable Entity{
"detail": [
"Password must be at least 8 characters",
"Password must contain at least one uppercase letter",
"Password must contain at least one digit"
]
}Password History
When PASSWORD_HISTORY_COUNT is set to a value greater than 0, users cannot reuse their last N passwords:
PASSWORD_HISTORY_COUNT=5 # Prevent reuse of last 5 passwordsResponse when reusing a password:
{
"detail": "Cannot reuse a recent password."
}Admin Dashboard
All lockout and password policy settings are configurable from the admin Settings page:
Settings
Configure authentication and system options
Authentication Methods
Password Policy
Security
Recommended Production Settings
# Balanced security (recommended)
ACCOUNT_LOCKOUT_ENABLED=true
ACCOUNT_LOCKOUT_ATTEMPTS=5
ACCOUNT_LOCKOUT_DURATION=1800
PASSWORD_MIN_LENGTH=12
PASSWORD_REQUIRE_UPPERCASE=true
PASSWORD_REQUIRE_LOWERCASE=true
PASSWORD_REQUIRE_DIGIT=true
PASSWORD_REQUIRE_SPECIAL=true
PASSWORD_HISTORY_COUNT=5Monitoring Lockouts
Query locked accounts via audit logs:
GET /api/v1/audit?event_type=auth&event_action=account_locked
Authorization: Bearer ADMIN_TOKENOr check for failed login patterns:
GET /api/v1/audit/failed-logins?ip_address=10.0.0.1
Authorization: Bearer ADMIN_TOKENAccess Control Rules
Row-level security with a powerful expression language. Control exactly who can list, view, create, update, delete, and manage records.
IP Filtering
CIDR-based IP allow and block rules to control access to your FastCMS instance. Supports IPv4, IPv6, expiring rules, and admin-managed entries.