Password Change Flow Implementation

Overview

This document describes the implementation of a proper password change flow that allows users with force_password_change=true to login with limited access solely to change their password.

Problem

Users with the force_password_change flag set (like the default admin) were caught in a catch-22:

  • They couldn’t login because password change was required
  • They couldn’t change their password without being logged in

Solution

1. Special Login Component (PasswordChangeLogin.jsx)

A dedicated login page at /password-change-login that:

  • Accepts email and current password
  • Validates credentials
  • Creates a limited session for password change only
  • Enforces strong password requirements
  • Provides visual feedback on password strength

2. Backend Endpoint (/api/auth/password-change-login)

Special endpoint that:

  • Verifies user credentials with Kratos
  • Checks if user has force_password_change=true
  • Creates a limited session with password_change_required=true
  • Only allows access to password change endpoints

3. Middleware Updates

The force_password_change.py middleware now allows:

  • Access to password_change_login endpoint
  • Limited session access for password changes
  • Blocks all other endpoints until password is changed

4. Authentication Flow Updates

The UnifiedAuthProvider now:

  • Detects PASSWORD_CHANGE_REQUIRED errors
  • Automatically redirects to /password-change-login
  • Prevents authentication loops

Usage

For Default Admin

  1. Navigate to https://localhost:8443/password-change-login
  2. Enter:
    • Email: admin@sting.local
    • Password: (from ~/.sting-ce/admin_password.txt)
  3. Set a new strong password
  4. System automatically logs you in after password change

For New Users

When creating users with temporary passwords:

  1. Set force_password_change: true in user traits
  2. Provide them the password change login URL
  3. They must change password on first login

Security Features

  • Strong password requirements (12+ chars, uppercase, lowercase, numbers, special)
  • Real-time password strength indicator
  • Limited session scope (only password change allowed)
  • Automatic session upgrade after password change
  • Secure password verification through Kratos

Alternative Solutions

  1. Clear Force Password Flag: python scripts/clear-force-password-change.py
  2. Create New Admin: python scripts/create-new-admin.py
  3. Reset Password: python scripts/reset_admin_password.py

These bypass security and should only be used in development or emergency situations.

Implementation Files

  • Frontend: /frontend/src/components/auth/PasswordChangeLogin.jsx
  • Backend: /app/routes/auth_routes.py (password_change_login endpoint)
  • Middleware: /app/middleware/force_password_change.py
  • Auth Provider: /frontend/src/auth/UnifiedAuthProvider.jsx
  • Route: /frontend/src/AppRoutes.js

Last updated: