Skip to content
P.M.C P.M.C P.M.C Documentation

Authentication & Two-Factor Authentication

1. What does this feature do? (High-Level Overview)

Section titled “1. What does this feature do? (High-Level Overview)”

The Authentication system provides secure access control for the application using a dual-token architecture (JWT access tokens + opaque refresh tokens) combined with optional Two-Factor Authentication (2FA). It supports multiple user types (employees and parents), flexible login identifiers (email or phone), and location-based permissions for employees.

2. Who is this for? (Roles & Permissions)

Section titled “2. Who is this for? (Roles & Permissions)”

User Types

Section titled “User Types”
  • Employees (Users): Medical staff, administrators, analysts who require location selection after authentication. Support roles include: SUPERADMIN, ADMIN, OWNER, MANAGER, BCBA, RBT, and more.
  • Parents: Family members with direct access to their children’s information without location selection.

Authentication Methods

Section titled “Authentication Methods”
  • Email-based login: Standard email and password authentication
  • Phone-based login: Phone number (normalized to 10 digits) and password authentication
  • Two-Factor Authentication: Optional SMS or Email verification (can be enforced globally)

3. Business Rules & Enforcements

Section titled “3. Business Rules & Enforcements”
  • Rule 1: Only ACTIVE users can authenticate. Users with BLACK_LIST status are rejected with 403 error.
  • Rule 2: Employees must select a location after authentication. Parents receive tokens immediately.
  • Rule 3: Location selection requires explicit access via user_locations table (no bypass for any role).
  • Rule 4: Admin View requires access_admin_view permission.
  • Rule 5: JWT access tokens expire after x time. Refresh tokens also expires after some time.
  • Rule 6: Refresh tokens use one-time rotation with reuse detection for security.
  • Rule 7: 2FA can be enforced globally in production.
  • Rule 8: 2FA codes expire after 10 minutes with maximum 5 verification attempts.
  • Rule 9: Backup codes are one-time use and can only be regenerated with password verification.
  • Rule 10: Password reset requires 2FA verification regardless of 2FA enablement status.

4. UI Placement

Section titled “4. UI Placement”

Login Page

Section titled “Login Page”
  • Location: /login (public route)
  • Components: Login form, 2FA method selection dialog, 2FA verification page, location selection dialog
  • Features: Email/phone input, password field, remember me, forgot password link

Two-Factor Authentication

Section titled “Two-Factor Authentication”
  • Setup Location: User Settings > Security > Two-Factor Authentication
  • Verification Page: /two-factor-verification (during login flow)
  • Features: Code input, resend code, use backup code, method selection (SMS/Email)

Password Reset

Section titled “Password Reset”
  • Location: /forgot-password (public route)
  • Flow: Request reset → Select method → Verify code → Change password
  • Pages: Forgot password, reset verification, change password

Session Management

Section titled “Session Management”
  • Location: User Settings > My Sessions
  • Features: View all active sessions, revoke individual sessions, revoke all other sessions

User Profile

Section titled “User Profile”
  • Location: Header > Profile dropdown
  • Features: Change password, enable/disable 2FA, manage backup codes

5. How-To Guide (Step-by-Step)

Section titled “5. How-To Guide (Step-by-Step)”

Scenario A: Standard Login (without 2FA)

See: Login Flow

Scenario B: Login with Two-Factor Authentication

See: Login Flow - Section on 2FA login

Scenario C: Enable/Disable Two-Factor Authentication

See: Two-Factor Authentication

Scenario D: Reset Forgotten Password

See: Password Reset

Scenario E: Manage Active Sessions

See: Session Management

6. What happens if…? (Edge Cases / FAQ)

Section titled “6. What happens if…? (Edge Cases / FAQ)”

  • Q: What happens if I enter an email address for a phone-only account?

    • A: The system auto-detects the identifier type. If you enter an email for a phone-only account, authentication will fail with “Invalid credentials.” Ensure you use the correct identifier (email or phone) associated with your account.

  • Q: Can I have multiple active sessions on different devices?

    • A: Yes, you can have multiple concurrent sessions. Each session is tracked independently with its own refresh token. You can view and manage all active sessions in User Settings > My Sessions.

  • Q: What happens if my 2FA code expires while I’m entering it?

    • A: The system automatically cleans up expired codes. You’ll receive an error message indicating the code has expired. Click “Resend Code” to receive a new verification code.

  • Q: What happens if I use all 5 verification attempts?

    • A: After 5 failed attempts, the verification code is automatically cleared. You must request a new code to continue. This prevents brute-force attacks.

  • Q: Can I use the same backup code twice?

    • A: No, backup codes are single-use only. After using a backup code, it’s removed from your account. You should regenerate new backup codes after using several of them.

  • Q: What happens if my refresh token is stolen and reused?

    • A: The system detects token reuse through family tracking. If a revoked token is presented again, the entire token family is revoked, invalidating all related sessions. This protects against token theft.

  • Q: Do I need 2FA for password reset?

    • A: Yes, password reset always requires 2FA verification regardless of whether you have 2FA enabled for login. This adds an extra layer of security when changing your password.

  • Q: Can I disable 2FA in production?

    • A: This depends on your organization’s policy. If 2FA is globally enforced in production, users cannot disable it. Only in non-production environments or when global enforcement is disabled can users toggle 2FA.

  • Q: What happens if I lose my phone and can’t receive SMS codes?

    • A: You can use the Email verification method instead, or use one of your backup codes. If you don’t have backup codes, contact your system administrator to reset your 2FA settings.

System Architecture

Section titled “System Architecture”

Dual-Token Authentication

Section titled “Dual-Token Authentication”
  • JWT Access Tokens: Short-lived (3 hours), used for API requests, contains user/permissions
  • Opaque Refresh Tokens: Long-lived (14 days), stored hashed, one-time use with rotation
  • Token Rotation: Each refresh generates a new token pair, revoking the old refresh token
  • Family Tracking: All rotated tokens share a family ID for reuse detection

Two-Factor Authentication

Section titled “Two-Factor Authentication”
  • Methods: SMS and Email
  • Code Storage: 6-digit codes stored as bcrypt hashes
  • Expiration: 10 minutes (UTC timezone)
  • Rate Limiting: 20 codes per hour per method
  • Backup Codes: 8 codes, 10 characters each, one-time use

Session Management

Section titled “Session Management”
  • AuthSession: Tracks refresh token sessions with device metadata
  • LoginSession: Audit trail for login events
  • Polymorphic: Supports both Users and Parents models

Security Features

Section titled “Security Features”
  • Permission-based access control
  • Location-scoped permissions for employees
  • Token reuse detection with family revocation
  • Rate limiting on sensitive endpoints
  • Comprehensive audit logging
  • Automatic code cleanup
  • Development mode bypass for testing

See detailed documentation: