UJ-M-001: Register or Login

Journey Overview

Attribute	Value
Journey ID	UJ-M-001
Actor	Prospective or existing member
Goal	Gain authenticated access to the Member Portal
Trigger	User navigates to member portal URL or clicks login link
Outcome	User is authenticated and redirected to dashboard

Preconditions

• User has a valid email address
• For SSO: Organization has configured SSO provider (WorkOS)
• For existing members: Account exists in the system

Journey Flow

flowchart TD
    A[User visits Member Portal] --> B{Has account?}
    B -->|No| C[Click Register]
    B -->|Yes| D[Click Login]
    C --> E[Enter registration details]
    E --> F[Verify email]
    F --> G[Complete profile]
    D --> H{SSO enabled?}
    H -->|Yes| I[Redirect to SSO provider]
    H -->|No| J[Enter email/password]
    I --> K[SSO authentication]
    J --> L[Validate credentials]
    K --> M[Issue JWT token]
    L --> M
    G --> M
    M --> N[Redirect to Dashboard]

Detailed Steps

1. Access Portal

   User navigates to the member portal URL (e.g., members.organization.com).

   System Response:

   • Displays login/register screen
   • Shows SSO button if configured for the organization
   • Shows email/password form as fallback
2. Choose Authentication Method

   User selects their preferred authentication method:

   Option A - SSO (if available):

   • Click "Continue with [Provider Name]"
   • Redirected to identity provider (Google, Microsoft, Okta, etc.)
   • Complete authentication with provider
   • Redirected back with auth token

   Option B - Email/Password:

   • Enter registered email address
   • Enter password
   • Click "Sign In"

   Option C - New Registration:

   • Click "Create Account" or "Register"
   • Proceed to registration flow
3. System Validates Credentials

   For SSO:

   • System validates OAuth token from provider
   • Matches user to existing account or creates new account
   • Retrieves user profile from provider (name, email, avatar)

   For Email/Password:

   • System validates email exists
   • System validates password hash matches
   • Checks account status (active, suspended, locked)

   Validation Failures:

   • Invalid credentials → "Invalid email or password"
   • Account locked → "Account locked. Contact support."
   • Account suspended → "Account suspended. Contact support."
4. Issue Authentication Token

   System issues JWT token containing:

   • User ID
   • Tenant ID (organization)
   • Role(s)
   • Token expiry

   Token is stored in:

   • HTTP-only secure cookie (primary)
   • Local storage (refresh token)
5. Redirect to Dashboard

   User is redirected to:

   • Dashboard (default)
   • Original requested URL (if deep-linked)
   • Profile completion page (if profile incomplete)

New Member Registration Flow

1. Enter Basic Information
   • Email address (required, unique)
   • First name (required)
   • Last name (required)
   • Password (required, min 8 chars, complexity rules)
   • Confirm password
2. Email Verification
   • System sends verification email with 6-digit code
   • User enters code within 15 minutes
   • System marks email as verified
3. Accept Terms
   • User reviews Terms of Service
   • User reviews Privacy Policy
   • User checks acceptance checkbox
4. Account Created
   • System creates user account
   • User redirected to profile completion

Error Scenarios

Scenario	System Response	User Action
Invalid email format	"Please enter a valid email address"	Correct email
Email already registered	"An account with this email already exists"	Use login or password reset
Incorrect password	"Invalid email or password"	Try again or reset password
Account locked (5 failed attempts)	"Account temporarily locked. Try again in 30 minutes."	Wait or contact support
SSO provider error	"Authentication failed. Please try again."	Retry or use email/password
Email not verified	"Please verify your email first"	Check inbox for verification email
Session expired	Redirect to login page	Re-authenticate

Password Reset Flow

1. Request Reset

   User clicks "Forgot Password" and enters email

2. Receive Email

   System sends password reset link (valid 1 hour)

3. Set New Password

   User clicks link and enters new password

4. Confirmation

   System updates password and redirects to login

Security Considerations

• Passwords hashed using bcrypt (cost factor 12)
• Rate limiting: 5 failed attempts = 30-minute lockout
• JWT tokens expire after 24 hours
• Refresh tokens expire after 7 days
• All auth endpoints use HTTPS only
• CSRF protection on all forms

Related Entities

• User/Member
• Audit Log

Related Journeys

• UJ-M-002
• UJ-M-003

Acceptance Criteria

Frontend

• Login form with email/password fields
• SSO button displayed when configured
• Registration form with validation
• Email verification code input
• Password reset flow implemented
• Loading states during authentication
• Error messages displayed clearly
• Remember me checkbox (extends session)

Backend

• POST /api/auth/login - Email/password login
• POST /api/auth/register - New user registration
• POST /api/auth/verify-email - Email verification
• POST /api/auth/forgot-password - Password reset request
• POST /api/auth/reset-password - Password reset completion
• GET /api/auth/sso/{provider} - SSO initiation
• POST /api/auth/sso/callback - SSO callback

Permissions

• Public access to login/register endpoints
• Rate limiting applied to auth endpoints

Business Rules

• Email must be unique per tenant
• Password complexity enforced
• Email verification required before full access
• SSO users cannot set password (SSO-only)

Error Handling

• Generic error for invalid credentials (security)
• Clear messages for account status issues
• Graceful SSO provider failure handling