Password Management & Recovery¶

This guide covers all supported password reset and account recovery paths for MCP Gateway administrators.

Overview¶

MCP Gateway supports:

• Self-service password reset (Forgot Password flow)
• Admin-initiated password resets and account unlocks
• API-based password reset/unlock automation
• Emergency database-level recovery for full lockout scenarios

Password hashes use Argon2id.

Self-Service Reset (Forgot Password)¶

User flow¶

1. User opens login page: /admin/login
2. Selects Forgot password?
3. Submits email at /admin/forgot-password
4. Receives one-time reset link by email
5. Sets a new password at /admin/reset-password/{token}

API endpoints¶

• POST /auth/email/forgot-password
• GET /auth/email/reset-password/{token}
• POST /auth/email/reset-password/{token}

Behavior:

• Reset tokens are one-time-use and hashed in DB
• Default token expiry: 60 minutes (PASSWORD_RESET_TOKEN_EXPIRY_MINUTES)
• Default rate limit: 5 requests / 15 minutes per email
• Forgot-password responses are generic to reduce account enumeration

If SMTP/email is not configured¶

When SMTP_ENABLED=false (default), forgot-password requests are still accepted and reset tokens are still generated, but no email is delivered.

In this mode, recovery options are:

1. Use Admin -> Users to set a new password directly.
2. Use admin API PUT /auth/email/admin/users/{email} to set a new password.
3. For break-glass scenarios, use the database recovery steps below.

Admin UI Reset & Unlock¶

Navigate to Admin -> Users (/admin/#users):

• Edit user and set a new password
• View lockout state (failed attempts, locked until)
• Click Unlock to clear lockout immediately

API-Based Admin Reset & Unlock¶

Reset user password¶

curl -X PUT "http://localhost:4444/auth/email/admin/users/user%40example.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "NewUserPassword123!",
    "password_change_required": false
  }'

Unlock user account¶

curl -X POST "http://localhost:4444/auth/email/admin/users/user%40example.com/unlock" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Kubernetes / Helm Recovery¶

Method 1: Helm bootstrap password update¶

# values.yaml
mcpContextForge:
  secret:
    PLATFORM_ADMIN_PASSWORD: "NewSecurePassword123!"

helm upgrade mcp-stack . -f values.yaml -n mcp-private
kubectl rollout status deployment/mcp-context-forge -n mcp-private

Method 2: Direct DB update¶

Generate hash inside gateway pod:

kubectl exec -n mcp-private -it deploy/mcp-context-forge -- \
  python -m mcpgateway.utils.hash_password

Apply hash in DB:

UPDATE email_users
SET password_hash = 'PASTE_HASH_HERE',
    password_change_required = false,
    failed_login_attempts = 0,
    locked_until = NULL,
    password_changed_at = CURRENT_TIMESTAMP
WHERE email = 'admin@example.com';

Emergency Full Lockout Procedure¶

1. Access database with platform credentials.
2. Identify admin users:

SELECT email, is_admin, failed_login_attempts, locked_until
FROM email_users
WHERE is_admin = true;

1. Reset password hash + unlock fields (query above).
2. Validate login via /admin/login.
3. Document incident and rotate temporary credentials.

Configuration¶

Password reset controls¶

• PASSWORD_RESET_ENABLED
• PASSWORD_RESET_TOKEN_EXPIRY_MINUTES
• PASSWORD_RESET_RATE_LIMIT
• PASSWORD_RESET_RATE_WINDOW_MINUTES
• PASSWORD_RESET_INVALIDATE_SESSIONS
• PASSWORD_RESET_MIN_RESPONSE_MS

SMTP notification controls¶

• SMTP_ENABLED
• SMTP_HOST
• SMTP_PORT
• SMTP_USER
• SMTP_PASSWORD
• SMTP_FROM_EMAIL
• SMTP_FROM_NAME
• SMTP_USE_TLS
• SMTP_USE_SSL
• SMTP_TIMEOUT_SECONDS

Lockout controls¶

• MAX_FAILED_LOGIN_ATTEMPTS
• ACCOUNT_LOCKOUT_DURATION_MINUTES
• ACCOUNT_LOCKOUT_NOTIFICATION_ENABLED