Authentication Overview

Production - AuthController - 7 endpoints

The authentication subsystem manages user identity verification through credential-based login, self-service registration, email verification, password reset, token refresh, and logout. All authentication endpoints are served by the AuthController at the /api/v1/auth path prefix.

Authentication Endpoints

Method	Endpoint	Description	Auth Required
POST	`/api/v1/auth/login`	Authenticate with email/password	No
POST	`/api/v1/auth/mfa/verify`	Complete MFA challenge	No
POST	`/api/v1/auth/register`	Self-service registration	No
POST	`/api/v1/auth/verify-email`	Verify email address	No
POST	`/api/v1/auth/resend-verification`	Resend verification code	No
POST	`/api/v1/auth/refresh`	Refresh access token	No
POST	`/api/v1/auth/logout`	Revoke refresh token	No

Authentication Flow Overview

The login flow supports both simple credential-based authentication and multi-factor authentication:

Client                  AuthController          AuthenticationService
  |                           |                          |
  |--- POST /auth/login ----->|                          |
  |                           |--- login() ------------->|
  |                           |                          |--- Validate credentials
  |                           |                          |--- Check account locked?
  |                           |                          |--- Check MFA enabled?
  |                           |                          |
  |                           |                    [MFA Enabled?]
  |                           |                     /         \
  |                           |                   Yes          No
  |                           |                    |            |
  |                           |<-- MfaChallengeResponse    AuthResponse
  |<-- 200 (MFA challenge) ---|                          |
  |                           |                          |
  |--- POST /auth/mfa/verify->|                          |
  |                           |--- verifyMfa() --------->|
  |                           |                          |--- Verify code
  |                           |                          |--- Generate tokens
  |<-- 200 (AuthResponse) ----|<-- AuthResponse ---------|

AuthResponse Structure

All successful authentication operations return an AuthResponse:

{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "displayName": "Jane Smith",
    "tenantId": "00000000-0000-0000-0000-000000000001",
    "roles": ["ROLE_USER"],
    "emailVerified": true
  }
}

Field	Type	Description
`accessToken`	String	JWT access token for API authentication
`refreshToken`	String	JWT refresh token for obtaining new access tokens
`tokenType`	String	Always `"Bearer"`
`expiresIn`	Long	Access token validity in seconds
`user`	UserInfo	Authenticated user profile

Security Considerations

IP Address Extraction: All authentication endpoints extract the client IP from X-Forwarded-For or RemoteAddr for audit logging and anomaly detection
User Agent Tracking: The User-Agent header is captured for device fingerprinting and session correlation
Account Lockout: Failed login attempts are tracked per user. After exceeding the configured threshold (default: 5 attempts), the account is locked for a configurable duration (default: 30 minutes)
Soft Delete: Deleted users are filtered out by the @SQLRestriction("deleted = false") annotation, making them invisible to authentication queries

Section Pages

Page	Description
Login Flow	Credential validation, MFA challenge, JWT token generation
Registration	Self-service registration with email verification
Email Verification	Verification code flow and resend logic
Password Reset	Forgot password and admin reset flows
Refresh Tokens	Token rotation, family tracking, reuse detection
Logout	Session termination and token revocation

IAM Architecture Login Flow