Password Management

Security protocols for managing user and client credentials, including real-time change validation and security notifications.

Change Password Flow

Users and Clients can update their current password. This process is secured by requiring the existing password and enforcing complexity/difference rules.

1. Request Change: The authenticated subject provides currentPassword and newPassword.
2. Validation:
   • Schema level: newPassword MUST be different from currentPassword.
   • Business level: currentPassword MUST match the stored hash.
3. Persistence: If valid, the new password is hashed (SHA-256) and the entity's passwordHash is updated.
4. Notification: An integration event (PasswordChangedIntegrationEvent) is published.

Sequence Diagram

sequenceDiagram
    participant User as Authenticated Subject
    participant API as User/Client Auth Controller
    participant Bus as CommandBus
    participant Handler as ChangePasswordHandler
    participant Geo as Geolocation Service
    participant DB as Identity Database
    participant Pub as IdentityPublisher

    User->>API: POST /auth/user/change-password {current, new}
    API->>Bus: Execute ChangeUserPasswordCommand
    Bus->>Handler: execute()
    Handler->>DB: Fetch entity
    Handler->>Handler: Verify currentPassword matches hash
    Handler->>Geo: Resolve location via IP (IGeolocationPort)
    Handler->>DB: Save entity with new hashed password
    Handler->>Pub: publishPasswordChanged()
    Pub-->>User: Security notification email (via EventBus)
    Handler-->>API: Result.ok
    API-->>User: 200 OK

Security Notifications

Every time a password is changed successfully, a notification email is sent to the account owner. This is a critical security measure to alert owners of unauthorized changes.

Email Content Includes:

• Device Info: Browser name and OS.
• IP Address: The origin of the change request.
• Geolocation: Physical location (resolved via Geolocation API) associated with the IP.
• Timestamp: Exact time of the modification.
• Next Steps: Advice on how to secure the account if the change was not authorized.

Scope

• Users: Fully supported through UserAuthController.
• Clients: Fully supported through ClientAuthController.

Unlike new-device login notifications (which are Users-only), Password Change notifications are sent to both Users and Clients.