🔐 Configurable Password Expiration with Forced Password Change on Login

Goal

Implement a configurable password expiration system for local users that:

1. Enforces password expiration after a configurable duration (e.g., 90 days)
2. Forces password change on login when password has expired
3. Supports first-login password change for newly created admin accounts
4. Provides grace period warnings before password expires
5. Maintains security compliance with organizational password policies

This enhances security by ensuring passwords are regularly rotated and that default/initial passwords are changed on first use.

Why Now?

Security best practices and compliance requirements (SOC2, ISO 27001, HIPAA) mandate regular password rotation:

1. Security Compliance: Many frameworks require passwords to expire after 60-90 days
2. First Login Security: Default admin passwords must be changed immediately on first use
3. Compromised Credential Risk: Regular rotation limits exposure from compromised credentials
4. Audit Requirements: Security audits require proof of password rotation policies
5. Zero Trust Architecture: Password expiration is a baseline security control
6. Account Takeover Prevention: Limits window of vulnerability for stolen credentials

📖 User Stories

Given I am a platform administrator
When I configure password expiration settings in .env:
  MCPGATEWAY_PASSWORD_EXPIRATION_DAYS=90
  MCPGATEWAY_PASSWORD_EXPIRATION_ENABLED=true
  MCPGATEWAY_PASSWORD_EXPIRATION_GRACE_PERIOD_DAYS=7
  MCPGATEWAY_PASSWORD_EXPIRATION_WARN_BEFORE_DAYS=14
  MCPGATEWAY_FORCE_PASSWORD_CHANGE_ON_FIRST_LOGIN=true

Then the system should:
  - Expire passwords after 90 days
  - Warn users 14 days before expiration
  - Allow 7-day grace period after expiration
  - Force password change on first login for new accounts
  - Lock accounts after grace period expires

When I disable password expiration:
  MCPGATEWAY_PASSWORD_EXPIRATION_ENABLED=false
Then existing password expiration dates should be preserved
But password expiration should not be enforced

Given I am a platform administrator
When I create a new admin user via CLI:
  mcpgateway users create \
    --username admin@example.com \
    --password "TempPass123!" \
    --role platform_admin \
    --force-password-change

Then the system should:
  - Create user with temporary password
  - Set force_password_change=true flag
  - Set password_must_change_at=current_timestamp
  - Log creation event in audit log

When I create a user via Admin UI:
  - Form shows "Force password change on first login" checkbox (checked by default)
  - User receives email with temporary password and warning
  - Email includes: "You must change your password on first login"

When the new user logs in for the first time:
  - They are redirected to password change page
  - They cannot access any other pages until password is changed
  - After successful password change, force_password_change=false
  - password_changed_at is updated to current timestamp
  - password_expires_at is set to current timestamp + expiration days

Given my password expires in 10 days
And MCPGATEWAY_PASSWORD_EXPIRATION_WARN_BEFORE_DAYS=14

When I log in
Then I should see a warning banner:
  "⚠️ Your password expires in 10 days. Please change it to avoid losing access."
  [Change Password Now] [Remind Me Later]

When I navigate to any page
Then the banner should persist (session-based, dismissible per session)

When I click "Change Password Now"
Then I am redirected to /admin/settings/change-password

When my password expires in 3 days
Then the warning should escalate:
  "🔴 Critical: Your password expires in 3 days!"
  - Banner turns red
  - Warning appears on every page
  - Cannot be dismissed

When I change my password
Then the warning disappears
And password_expires_at is extended by expiration days

Given my password expired 2 days ago
And I am within the grace period (7 days)

When I log in
Then I should be redirected to /admin/settings/change-password-required
And I should see:
  "Your password has expired. You must change it to continue."
  - Current password field
  - New password field (with strength requirements)
  - Confirm new password field
  - [Change Password] button

When I submit the form with valid passwords
Then the system should:
  - Validate current password
  - Validate new password meets requirements (length, complexity)
  - Update password hash
  - Set password_changed_at=current_timestamp
  - Set password_expires_at=current_timestamp + expiration days
  - Set force_password_change=false
  - Redirect to original destination or dashboard
  - Log password change event in audit log

When I try to access any other page before changing password
Then I should be redirected back to password change page
With message: "You must change your password before continuing."

When my password expired more than grace period days ago
Then login should fail with:
  "Your account has been locked due to expired password. Please contact your administrator."

Given I am logged in
When I navigate to My Settings > Change Password
Then I should see:
  - Current password field
  - New password field
  - Confirm new password field
  - Password strength indicator
  - [Change Password] button
  - Last changed: "14 days ago"
  - Expires in: "76 days"

When I enter my current password incorrectly
Then I should see error: "Current password is incorrect"

When I enter a weak new password
Then I should see error: "Password must be at least 12 characters and include uppercase, lowercase, numbers, and symbols"

When I reuse my current password
Then I should see error: "New password cannot be the same as current password"

When I successfully change my password
Then the system should:
  - Update password hash
  - Update password_changed_at
  - Extend password_expires_at by expiration days
  - Invalidate all existing sessions (optional, configurable)
  - Send confirmation email
  - Log event in audit log
  - Show success message: "Password changed successfully. Expires on YYYY-MM-DD."

Given I am a platform administrator
When I navigate to Admin > Users
Then I should see password status columns:
  - Last Changed: "2024-10-15 (3 days ago)"
  - Expires: "2025-01-13 (87 days)" [color: green]
  - Status: "Active" | "Expiring Soon" | "Expired" | "Grace Period" | "Locked"

When I filter by status "Expiring Soon"
Then I should see users whose passwords expire within warn_before_days

When I filter by status "Grace Period"
Then I should see users whose passwords expired but are within grace period

When I filter by status "Locked"
Then I should see users whose passwords expired beyond grace period

When I click on a user
Then I should see password details:
  - Password created: "2024-10-15"
  - Password last changed: "2024-10-15 (3 days ago)"
  - Password expires: "2025-01-13 (in 87 days)"
  - Force password change: No
  - Password change history: [table of last 10 changes with timestamps]

When I click "Force Password Change"
Then the system should:
  - Set force_password_change=true
  - Set password_must_change_at=current_timestamp
  - Send email to user: "Admin has required you to change your password"
  - Log admin action in audit log

Given I am a platform administrator
And user "alice@example.com" has a locked account (password expired beyond grace period)

When I navigate to Admin > Users > alice@example.com
And I click "Reset Password"
Then I should see a form:
  - New temporary password (auto-generated or manual entry)
  - [x] Force password change on next login (checked, non-editable)
  - [x] Send password reset email
  - Reason for reset: [text field for audit]
  - [Reset Password] button

When I submit the form
Then the system should:
  - Generate temporary password (if auto-generated): strong, random, 16 chars
  - Update user password hash
  - Set force_password_change=true
  - Set password_must_change_at=current_timestamp
  - Set password_changed_at=current_timestamp
  - Unlock account (if locked)
  - Send email to user with temporary password
  - Log admin action in audit log: "Admin bob@example.com reset password for alice@example.com. Reason: Account recovery."

When alice logs in with temporary password
Then she is forced to change password (see US-4)

When alice changes password
Then account returns to normal operation

Given MCPGATEWAY_PASSWORD_HISTORY_COUNT=5
And I have changed my password 5 times previously

When I try to change my password to one of my last 5 passwords
Then the system should:
  - Hash the new password and compare with password history
  - Reject with error: "You cannot reuse any of your last 5 passwords"

When I change to a truly new password
Then the system should:
  - Accept the new password
  - Add old password hash to password_history table
  - Keep only last 5 password hashes (delete older ones)
  - Update password_changed_at and password_expires_at

When MCPGATEWAY_PASSWORD_HISTORY_COUNT=0
Then password reuse prevention should be disabled

🏗 Architecture

Password Lifecycle

stateDiagram-v2
    [*] --> UserCreated: Admin creates user
    UserCreated --> ForceChange: force_password_change=true
    UserCreated --> Active: force_password_change=false
    
    ForceChange --> PasswordChangePage: User logs in
    PasswordChangePage --> Active: User changes password
    
    Active --> WarningSoon: Expires in < warn_before_days
    WarningSoon --> WarningCritical: Expires in < 3 days
    WarningCritical --> Expired: Password expires
    
    Expired --> GracePeriod: Within grace period
    GracePeriod --> Active: User changes password
    GracePeriod --> Locked: Grace period ends
    
    Locked --> ForceChange: Admin resets password
    Active --> ForceChange: Admin forces password change

Database Schema

-- Extend users table
ALTER TABLE users ADD COLUMN password_changed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP;
ALTER TABLE users ADD COLUMN password_expires_at TIMESTAMP;
ALTER TABLE users ADD COLUMN force_password_change BOOLEAN DEFAULT FALSE;
ALTER TABLE users ADD COLUMN password_must_change_at TIMESTAMP;
ALTER TABLE users ADD COLUMN account_locked BOOLEAN DEFAULT FALSE;
ALTER TABLE users ADD COLUMN account_locked_reason VARCHAR(255);
ALTER TABLE users ADD COLUMN account_locked_at TIMESTAMP;

-- Create index for expiration queries
CREATE INDEX idx_users_password_expires_at ON users(password_expires_at);
CREATE INDEX idx_users_force_password_change ON users(force_password_change);

-- Password history table
CREATE TABLE password_history (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_password_history_user_id (user_id),
    INDEX idx_password_history_created_at (created_at)
);

-- Password policy audit log
CREATE TABLE password_audit_log (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    action VARCHAR(50) NOT NULL,  -- 'changed', 'expired', 'forced_change', 'reset_by_admin', 'account_locked'
    performed_by UUID REFERENCES users(id),  -- NULL if self-service
    reason TEXT,
    ip_address INET,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_password_audit_user_id (user_id),
    INDEX idx_password_audit_action (action),
    INDEX idx_password_audit_timestamp (timestamp)
);

Configuration

# Password Expiration Settings
MCPGATEWAY_PASSWORD_EXPIRATION_ENABLED=true
MCPGATEWAY_PASSWORD_EXPIRATION_DAYS=90              # Expire after 90 days
MCPGATEWAY_PASSWORD_EXPIRATION_WARN_BEFORE_DAYS=14  # Warn 14 days before
MCPGATEWAY_PASSWORD_EXPIRATION_GRACE_PERIOD_DAYS=7  # 7-day grace period after expiration

# First Login Policy
MCPGATEWAY_FORCE_PASSWORD_CHANGE_ON_FIRST_LOGIN=true

# Password Strength Requirements
MCPGATEWAY_PASSWORD_MIN_LENGTH=12
MCPGATEWAY_PASSWORD_REQUIRE_UPPERCASE=true
MCPGATEWAY_PASSWORD_REQUIRE_LOWERCASE=true
MCPGATEWAY_PASSWORD_REQUIRE_NUMBERS=true
MCPGATEWAY_PASSWORD_REQUIRE_SYMBOLS=true

# Password Reuse Prevention
MCPGATEWAY_PASSWORD_HISTORY_COUNT=5  # Prevent reuse of last 5 passwords

# Session Management
MCPGATEWAY_INVALIDATE_SESSIONS_ON_PASSWORD_CHANGE=true  # Log out all sessions on password change

📋 Implementation Tasks

Phase 1: Database Schema & Models ✅

• Alembic Migration

  • Add columns to users table: password_changed_at, password_expires_at, force_password_change, password_must_change_at, account_locked, account_locked_reason, account_locked_at
  • Create password_history table
  • Create password_audit_log table
  • Add indexes for performance

• SQLAlchemy ORM Models

  • Update User model with new fields
  • Create PasswordHistory model
  • Create PasswordAuditLog model
  • Add relationships and helper methods

• Repository Layer

  • Methods: check_password_expired(), days_until_expiration(), is_in_grace_period()
  • Methods: add_password_to_history(), check_password_reuse()
  • Methods: log_password_event()

Phase 2: Password Policy Service ✅

• PasswordPolicyService

  • Method: calculate_expiration_date(user)
  • Method: check_password_strength(password) -> bool, errors
  • Method: validate_password_change(user, current_pw, new_pw) -> bool, errors
  • Method: enforce_password_history(user, new_password_hash) -> bool
  • Method: send_expiration_warning_email(user, days_remaining)
  • Method: lock_account_expired_password(user)

• Password Strength Validation

  • Check minimum length
  • Check character requirements (uppercase, lowercase, numbers, symbols)
  • Check against common passwords list
  • Check for user information (username, email) in password
  • Return detailed error messages

• Background Jobs

  • Daily cron job: Check for expiring passwords → send warning emails
  • Daily cron job: Check for expired passwords beyond grace period → lock accounts
  • Email templates: 14-day warning, 7-day warning, 3-day critical, expired, account locked

Phase 3: Authentication Middleware ✅

• Password Expiration Middleware

  • Check password_expires_at on every authenticated request
  • If expired and within grace period → redirect to /admin/settings/change-password-required
  • If expired beyond grace period → lock account, redirect to login with error
  • If force_password_change=true → redirect to /admin/settings/change-password-required
  • Whitelist routes: /admin/settings/change-password-required, /auth/logout, /health

• Warning Banner Middleware

  • Calculate days until expiration
  • If within warn_before_days → inject warning banner data into response
  • Check session variable: password_warning_dismissed
  • If critical (< 3 days) → non-dismissible banner

Phase 4: API Endpoints ✅

• Password Change API

  • POST /users/me/change-password - Self-service password change
    • Request: {current_password, new_password, confirm_password}
    • Validate current password
    • Validate new password strength
    • Check password history
    • Update password, extend expiration
    • Invalidate sessions (if configured)
    • Send confirmation email
    • Log audit event

• Admin Password Management API

  • POST /admin/users/{id}/force-password-change - Admin forces password change
  • POST /admin/users/{id}/reset-password - Admin resets password with temporary password
  • GET /admin/config/password-policy - Get password policy settings
  • PUT /admin/config/password-policy - Update password policy (platform admin only)

• User Password Status API

  • GET /users/me/password-status - Get my password status
    • Response: {password_changed_at, password_expires_at, days_until_expiration, force_password_change, status}

Phase 5: Admin UI Pages ✅

• Change Password Page (Self-Service)

  • Page: /admin/settings/change-password
  • Form: Current password, new password, confirm password
  • Password strength meter (real-time)
  • Requirements checklist (✓ 12+ chars, ✓ uppercase, etc.)
  • Show last changed date and expiration date
  • Success/error messages

• Forced Password Change Page

  • Page: /admin/settings/change-password-required
  • Blocking modal (cannot dismiss)
  • Message: "Your password has expired. You must change it to continue."
  • Same form as self-service change password
  • On success: redirect to original destination

• Password Expiration Warning Banner

  • Component: PasswordExpirationBanner
  • Color coding: Yellow (14-7 days), Orange (7-3 days), Red (3-0 days)
  • Dismissible (session-based) unless critical
  • Button: "Change Password Now" → /admin/settings/change-password
  • Inject into all pages via middleware

• Admin User Management - Password Status

  • Extend: /admin/users table
  • Columns: Last Changed, Expires, Status (badge with color)
  • Filters: Status (All, Active, Expiring Soon, Expired, Locked)
  • Actions: Force Password Change, Reset Password

• Admin User Details - Password Tab

  • Tab: Password on user details page
  • Show: password_changed_at, password_expires_at, force_password_change, account_locked
  • Show: Password change history (last 10 changes)
  • Buttons: Force Password Change, Reset Password, Unlock Account

• Admin Password Policy Settings

  • Page: /admin/config/password-policy
  • Form fields:
    • Enable password expiration (checkbox)
    • Expiration days (number input)
    • Warning days (number input)
    • Grace period days (number input)
    • Force change on first login (checkbox)
    • Password history count (number input)
    • Minimum length, character requirements (checkboxes)
  • Validation: grace period < expiration
  • Save button → updates environment config

Phase 6: CLI Commands ✅

• User Creation with Forced Password Change

  • Command: mcpgateway users create --username --password --role --force-password-change
  • Set force_password_change=true
  • Send email with temporary password

• Admin Password Reset

  • Command: mcpgateway users reset-password --username --reason
  • Generate temporary password
  • Set force_password_change=true
  • Send email

• Check Password Expiration Status

  • Command: mcpgateway users password-status --username
  • Show: last changed, expires, days remaining, status

• List Users by Password Status

  • Command: mcpgateway users list --password-status expiring-soon
  • Filters: active, expiring-soon, expired, grace-period, locked

Phase 7: Background Jobs ✅

• Password Expiration Monitor (Daily Cron)

  • Run daily at 00:00 UTC
  • Query users where password expires within warn_before_days
  • Send warning emails (14-day, 7-day, 3-day templates)
  • Log events in password_audit_log

• Account Locking Job (Daily Cron)

  • Run daily at 01:00 UTC
  • Query users where password expired beyond grace period
  • Lock accounts: account_locked=true, account_locked_reason="Password expired"
  • Send account locked email
  • Log events

• Email Templates

  • Template: password_expiring_14_days.html
  • Template: password_expiring_7_days.html
  • Template: password_expiring_3_days.html (critical)
  • Template: password_expired.html
  • Template: account_locked_expired_password.html
  • Template: password_changed_confirmation.html
  • Template: admin_forced_password_change.html
  • Template: temporary_password.html

Phase 8: Testing ✅

• Unit Tests

  • Test password expiration calculation
  • Test password strength validation (all requirements)
  • Test password history check (reuse prevention)
  • Test grace period logic
  • Test account locking logic
  • Test warning banner visibility rules
  • Test forced password change flow

• Integration Tests

  • Test full workflow: User created → forced password change → login → change password → active
  • Test expiration flow: Active → warning → expired → grace period → locked
  • Test admin reset: Locked account → admin resets → user changes password → active
  • Test password reuse prevention
  • Test session invalidation on password change

• E2E Tests (Playwright)

  • Test user login with expired password → forced password change page → change password → dashboard
  • Test user login with first-time password → forced password change → success
  • Test self-service password change from settings
  • Test admin force password change → user login → forced change
  • Test admin reset password → email received → user login with temp password → forced change
  • Test warning banner display and dismissal

• Security Tests

  • Test password strength requirements enforcement
  • Test password history prevents reuse
  • Test grace period cannot be bypassed
  • Test forced password change cannot be bypassed (direct URL access blocked)
  • Test session invalidation works correctly

Phase 9: Documentation ✅

• User Guide

  • Document: How to change password
  • Document: What happens when password expires
  • Document: Grace period and account locking
  • Document: Password strength requirements

• Admin Guide

  • Document: How to configure password policy
  • Document: How to force password change for users
  • Document: How to reset passwords
  • Document: How to unlock locked accounts
  • Document: How to monitor password expiration status

• API Documentation

  • OpenAPI spec for password change endpoints
  • Example API calls

Phase 10: Quality & Polish ✅

• Code Quality

  • Run make autoflake isort black
  • Run make flake8 and fix all issues
  • Run make pylint and address warnings
  • Pass make verify checks

• Security Review

  • Review password storage (bcrypt/argon2)
  • Review password history storage (separate hashes)
  • Review forced password change enforcement (no bypass)
  • Review audit logging completeness
  • Review email content (no passwords in logs)

✅ Success Criteria

• Password Expiration: Passwords expire after configurable days (default 90)
• Forced Password Change: New users must change password on first login
• Grace Period: Users can still log in for N days after expiration to change password
• Account Locking: Accounts lock after grace period expires
• Warning System: Users receive warnings 14, 7, 3 days before expiration
• Password Strength: Strong password requirements enforced
• Password History: Users cannot reuse last N passwords
• Admin Controls: Admins can force password change and reset passwords
• Audit Trail: All password events logged
• Email Notifications: Users receive emails at key events
• Session Security: Sessions optionally invalidated on password change
• UI/UX: Clean, intuitive password change flows
• Testing: 100+ tests with 90%+ coverage
• Documentation: Complete user and admin guides

🏁 Definition of Done

• Database schema migrated (3 new tables/columns)
• ORM models and repository layer complete
• PasswordPolicyService implemented and tested
• Password strength validation working
• Password history and reuse prevention working
• Authentication middleware for forced password change
• Warning banner middleware
• API endpoints: change password, force change, reset, status
• Admin UI: password policy settings, user password management
• User UI: self-service password change, forced change page
• CLI commands: create user with forced change, reset password
• Background jobs: expiration monitor, account locking
• Email templates: warnings, expiration, locked, reset
• 100+ unit tests with 90%+ coverage
• Integration tests for all workflows
• E2E tests (Playwright) for UI flows
• Security review completed
• Documentation complete (user guide, admin guide, API docs)
• Code passes make verify checks
• Ready for production deployment

📝 Additional Notes

🔹 Design Principles:

• Security by Default: Strong password requirements and expiration enabled out of the box
• User-Friendly: Clear warnings and grace periods prevent lockouts
• Compliance-Ready: Meets SOC2, ISO 27001, HIPAA password rotation requirements
• Auditable: Complete audit trail for compliance and security investigations

🔹 Use Cases:

• First Login Security: Admins create accounts with temporary passwords that must be changed
• Regular Rotation: Passwords automatically expire every 90 days
• Incident Response: Admins can force password changes for compromised accounts
• Compliance Audits: Export password change history and policy settings

🔹 Future Enhancements:

• Password Complexity Scoring: Use zxcvbn for real-time strength scoring
• Passwordless Authentication: Support WebAuthn, FIDO2 as alternatives
• Adaptive Expiration: Longer expiration for MFA-enabled accounts
• Breach Detection: Check passwords against HaveIBeenPwned API
• Self-Service Account Recovery: Secure password reset via email/SMS

🔹 Security Considerations:

• Store passwords with bcrypt/argon2 (high cost factor)
• Store password history hashes separately (prevent rainbow table attacks)
• Rate limit password change attempts (prevent brute force)
• Log all password events with IP addresses
• Never log plaintext passwords
• Send temporary passwords via secure channel (encrypted email, SMS)

🔗 Related Issues

• [FEATURE][SECURITY]: Make users change default admin passwords for production #974

📚 References

• NIST Password Guidelines (SP 800-63B)
• OWASP Password Storage Cheat Sheet
• SOC 2 Password Requirements
• ISO 27001 Password Policy