Skip to content

User Authentication

User Scenarios & Testing

User Story 1 - Basic Email/Password Authentication (Priority: P1)

Users need to log into the Conference Expo Portal using their email and password to access their dashboard and manage events, stands, or artwork. The system must verify their identity and provide secure access with persistent sessions across page navigation.

Why this priority: This is the foundation of the entire authentication system. Without basic login/logout, no other features can function. This represents the minimum viable authentication that delivers immediate value.

Independent Test: Can be fully tested by creating a user account, logging in with valid credentials, accessing protected pages, and logging out. Delivers immediate value by enabling secure access to the platform.

Acceptance Scenarios:

  1. Given a user with valid email and password credentials, When they submit their authentication details, Then they gain access to their appropriate dashboard based on their role (organiser, sponsor, or administrator) and receive authentication tokens
  2. Given an authenticated user with an active session, When they navigate between pages within the platform, Then they remain authenticated without re-entering credentials through automatic token refresh
  3. Given a user with invalid credentials, When they attempt to authenticate, Then they receive clear feedback indicating the authentication failed without revealing which specific credential was incorrect
  4. Given an authenticated user, When they explicitly log out, Then their session tokens are revoked and they cannot access protected resources without re-authenticating
  5. Given a user who has been inactive, When their access token expires (15 minutes), Then the system automatically obtains a new access token using their refresh token without requiring re-authentication
  6. Given a user whose refresh token has expired (30 days), When they attempt to access protected resources, Then they are prompted to re-authenticate
  7. Given an unauthenticated user navigating directly to a protected URL, When the system checks their authentication status, Then they are redirected to login and returned to their intended destination after successful authentication

User Story 2 - Password Reset and Security (Priority: P1)

Users who forget their password need a secure way to reset it via email, and the system must protect against brute force attacks while maintaining security across all user sessions.

Why this priority: Critical for user autonomy and security. Without password reset, users cannot recover access to their accounts. Without brute force protection, the system is vulnerable to attacks. Both are essential for a production-ready authentication system.

Independent Test: Can be fully tested by initiating password reset, receiving and using the reset link, setting a new password, and verifying old sessions are invalidated. Security can be tested by attempting multiple failed logins and verifying rate limiting.

Acceptance Scenarios:

  1. Given a user who has forgotten their password, When they initiate password reset, Then they receive a one-time use reset link via email valid for 1 hour
  2. Given a user with a valid password reset link, When they set a new password meeting complexity requirements (8+ characters, uppercase, lowercase, number), Then all their existing sessions are invalidated and they must log in again on all devices
  3. Given a user attempting multiple failed logins, When the system detects excessive authentication attempts, Then configurable rate limiting is applied to prevent brute force attacks
  4. Given a user with an expired or already-used password reset link, When they attempt to use it, Then the link is invalid and they must request a new reset link
  5. Given a user whose account is deactivated or whose role changes, When the system processes this change, Then all refresh tokens are immediately revoked (preventing new access tokens) and existing access tokens remain valid up to 15 minutes until natural expiration

User Story 3 - Multi-Device and "Remember Me" Support (Priority: P2)

Users need to access the platform from multiple devices simultaneously (desktop, tablet, mobile) and have the option to stay logged in across browser sessions with "remember me" functionality.

Why this priority: Important for user convenience and real-world usage patterns, but the system can function without it initially. Users can still authenticate on single devices. This enhances the experience but isn't blocking.

Independent Test: Can be fully tested by logging in on multiple devices simultaneously, verifying independent sessions, using "remember me" option, closing/reopening browser, and verifying persistent authentication.

Acceptance Scenarios:

  1. Given a user authenticated on multiple devices, When they perform actions on one device, Then their authentication remains valid on all devices unless explicitly logged out or their account is deactivated
  2. Given a user attempting to authenticate while already having an active session, When they log in, Then they receive a new set of tokens without affecting existing sessions on other devices
  3. Given a user who enabled "remember me" during login, When they close and reopen their browser, Then they remain authenticated without re-entering credentials (persistent cookie with configurable duration)
  4. Given a user who disabled "remember me" during login, When they close and reopen their browser, Then they must re-authenticate (session cookie deleted on browser close)
  5. Given a user who updates their password, When the system processes the credential change, Then all existing refresh tokens are revoked requiring re-authentication on all devices

User Story 4 - Passwordless Authentication (Priority: P2)

Users need an alternative authentication method that doesn't require remembering passwords, using email-based verification codes or links to access the platform securely.

Why this priority: Enhances security and user experience by providing a modern alternative to passwords, but email/password authentication is sufficient for MVP. This is a valuable enhancement but not essential for initial launch.

Independent Test: Can be fully tested independently by requesting passwordless login, receiving verification code via email, submitting code, and gaining access to the platform without ever using a password.

Acceptance Scenarios:

  1. Given a user choosing passwordless authentication, When they enter their email address, Then they receive a time-limited verification code or link via email
  2. Given a user with a valid verification code, When they submit it, Then they are authenticated and receive access tokens, gaining access to their dashboard
  3. Given a user with an expired verification code, When they attempt to use it, Then authentication fails and they must request a new code
  4. Given a user authenticating via passwordless method, When they later access a scope requiring 2FA (different from primary auth), Then they receive a separate 2FA verification challenge

User Story 5 - Third-Party OAuth Authorization (Priority: P3)

External third-party applications need to integrate with the Conference Expo API through OAuth-style authorization where users grant specific permissions (scopes) to these external applications for delegated access.

Why this priority: Important for future ecosystem growth and external integrations, but not needed for platform launch. The system serves its primary purpose without third-party integrations. This enables future extensibility. Note: P1 covers authentication for the platform's own frontend/backend - this story is specifically for external third-party app integration with user consent screens.

Independent Test: Can be fully tested independently by registering a third-party application, initiating OAuth flow, approving scopes, receiving tokens, making API requests within scope, and attempting out-of-scope requests.

Acceptance Scenarios:

  1. Given a third-party application seeking access to the API, When a user reviews the authorization request, Then they see the requested permission scopes and application details on a consent screen
  2. Given a user approving third-party authorization, When they grant permission, Then the application receives access credentials limited to only the approved scopes (e.g., events:read, stands:write)
  3. Given a third-party application with limited scopes, When it attempts to access an API endpoint outside its approved scopes, Then the request is denied with a clear scope violation error
  4. Given a user who wants to revoke third-party access, When they revoke authorization, Then the authorization is immediately removed from database, refresh tokens cannot obtain new access tokens, and existing access tokens remain valid up to 15 minutes until natural expiration
  5. Given a third-party application with valid tokens, When they make API requests within their approved scopes, Then the requests are processed successfully with appropriate access control

User Story 6 - Two-Factor Authentication (2FA) for Sensitive Scopes (Priority: P3)

Users and third-party applications need additional security verification when accessing sensitive operations through scope-based 2FA using authenticator apps (TOTP) or email verification codes.

Why this priority: Enhances security for sensitive operations, but basic authentication is sufficient for initial platform usage. This is a valuable security enhancement for production but can be added after core authentication is stable.

Independent Test: Can be fully tested independently by setting up authenticator app, configuring 2FA, accessing 2FA-protected scope, providing TOTP code, and verifying access is granted only with valid 2FA verification.

Acceptance Scenarios:

  1. Given a user setting up 2FA, When they configure an authenticator app, Then they receive a secret key and can generate time-based one-time passwords (TOTP) for subsequent challenges
  2. Given a user without an authenticator app configured, When 2FA is required for a scope, Then they receive a time-limited verification code via email as a fallback method
  3. Given a user or third-party application attempting to access a scope requiring 2FA, When they make the request, Then they must provide valid 2FA verification (authenticator code or email code) before access is granted
  4. Given a user with invalid or expired 2FA codes, When they attempt verification, Then the system applies rate limiting to prevent brute force attacks on verification codes
  5. Given a user who loses access to their authenticator device, When they need to access 2FA-protected scopes, Then they can use email-based verification codes to regain access and reconfigure their authenticator
  6. Given a scope's 2FA requirement is changed in configuration, When the change takes effect, Then existing tokens remain valid until expiration but new requests enforce the updated 2FA requirement

Edge Cases

  • Multiple device access: Users can authenticate on multiple devices simultaneously, with sessions remaining independent and valid across all devices
  • Account status changes: When a user's account is deactivated or role changes, all refresh tokens are immediately revoked (preventing new access tokens), but existing access tokens remain valid up to 15 minutes until natural expiration
  • Existing active session: Users attempting to authenticate while already having an active session will receive a new set of tokens without affecting existing sessions on other devices
  • Repeated failed authentication: System applies configurable rate limiting on authentication attempts to protect against brute force attacks
  • Credential updates: When a user updates their authentication credentials (password change or password reset), all existing refresh tokens are revoked requiring re-authentication on all devices
  • Expired password reset link: When a user attempts to use a password reset link after 1 hour expiration or after it's already been used, the link is invalid and user must request a new reset link
  • Direct URL access: Unauthenticated users navigating directly to protected URLs are redirected to authentication, then returned to their intended destination after successful login
  • Passwordless vs 2FA codes (P2/P3): Email-based passwordless login (primary auth) and email-based 2FA (secondary auth) are separate features - a user could authenticate via passwordless email code, then later trigger 2FA email code when accessing sensitive scope

P3 Edge Cases (Third-Party OAuth & 2FA)

  • Third-party revocation: When a user revokes authorization for a third-party application, the authorization is immediately removed from database (preventing new tokens), refresh tokens cannot be used to obtain new access tokens, but existing access tokens remain valid up to 15 minutes until natural expiration (standard stateless JWT behavior)
  • 2FA requirement changes: When a scope's 2FA requirement is changed in configuration, existing tokens for that scope remain valid until expiration but new requests to that scope enforce the updated 2FA requirement
  • 2FA method unavailable: When a user without an authenticator app configured attempts to access a 2FA-required scope, the system automatically sends an email verification code as fallback
  • Lost authenticator device: Users who lose access to their authenticator app can use email-based verification codes to access 2FA-protected scopes and reconfigure their authenticator
  • Invalid 2FA codes: System applies rate limiting to 2FA verification attempts to prevent brute force attacks on verification codes

Requirements

Functional Requirements

Core Authentication (P1)

  • FR-001: System MUST verify user identity before granting access to any protected resources
  • FR-002: System MUST support email/password authentication as primary authentication method
  • FR-003: System MUST enforce minimum password complexity of 8 characters including at least one uppercase letter, one lowercase letter, and one number
  • FR-004: System MUST maintain user sessions that persist across page navigation within the platform
  • FR-005: System MUST terminate sessions when users explicitly log out
  • FR-006: System MUST automatically expire access tokens after 15 minutes and refresh tokens after 30 days
  • FR-007: System MUST distinguish between different user types (organisers, sponsors, administrators) and route them appropriately after authentication
  • FR-008: System MUST prevent access to protected resources for unauthenticated users
  • FR-009: System MUST display clear, user-friendly error messages when authentication fails without revealing sensitive security information
  • FR-010: System MUST handle the transition from unauthenticated to authenticated state smoothly, redirecting users to their intended destination after successful authentication
  • FR-011: System MUST provide clear visual indication of authentication status throughout the user interface
  • FR-012: System MUST maintain authentication tokens securely so that tokens cannot be hijacked or forged (HTTPS only, HttpOnly cookies for refresh tokens, secure token generation)

Password Reset and Security (P1)

  • FR-013: System MUST provide password reset mechanism that sends time-limited reset link (valid 1 hour) via email
  • FR-014: Password reset links MUST be one-time use only
  • FR-015: Upon successful password reset, all existing refresh tokens MUST be revoked requiring users to re-authenticate on all devices
  • FR-016: System MUST protect against brute force attacks through configurable rate limiting on authentication endpoints
  • FR-017: System MUST immediately revoke all refresh tokens when a user's account is deactivated or their role changes (preventing new access tokens). Existing access tokens remain valid until natural expiration (max 15 minutes)
  • FR-018: System MUST log all authentication events (successful logins, failed attempts, logouts) for security auditing

Multi-Device Support (P2)

  • FR-019: System MUST allow concurrent sessions from the same user account across multiple devices
  • FR-020: System MUST allow users to have multiple active sessions on different devices simultaneously
  • FR-021: System MUST provide optional "remember me" functionality that controls refresh token cookie persistence. When enabled, refresh token stored as persistent cookie (duration configurable). When disabled, refresh token stored as session cookie (deleted when browser closes)
  • FR-022: When a user updates their authentication credentials, all existing refresh tokens MUST be revoked requiring re-authentication on all devices

Passwordless Authentication (P2)

  • FR-023: System MUST support passwordless authentication via email-based verification as alternative primary authentication method
  • FR-024: For passwordless authentication, system MUST send time-limited verification codes or links to the user's registered email address
  • FR-025: Email-based passwordless codes MUST be separate from email-based 2FA codes (primary vs secondary authentication)

Single Sign-On (P2)

  • FR-026: System MUST support single sign-on, allowing users to access all conference events they have permission for with one authentication

Third-Party OAuth (P3 - External App Integration)

Note: These requirements are for external third-party applications integrating with the platform (with user consent screens). P1 covers authentication for the platform's own frontend/backend clients.

  • FR-027: System MUST support granular permission scopes for third-party applications based on resource types and actions (e.g., events:read, stands:write, artwork:read)
  • FR-028: System MUST present requested scopes to users for approval before authorizing third-party applications
  • FR-029: System MUST enforce scope-based access control on all API endpoints, denying requests that exceed granted scopes
  • FR-030: Third-party application tokens MUST be limited to only the scopes explicitly approved by the user
  • FR-031: System MUST revoke third-party application authorization when user revokes access, preventing issuance of new tokens. Existing access tokens remain valid until natural expiration (max 15 minutes), existing refresh tokens become invalid immediately

Two-Factor Authentication (P3)

  • FR-032: System MUST allow users to set up authenticator apps using TOTP (Time-based One-Time Password) standard for secondary authentication (2FA) verification
  • FR-033: System MUST support email-based verification codes as a fallback secondary authentication (2FA) method when users have not configured an authenticator app
  • FR-034: Certain permission scopes MUST be configured to require 2FA verification (secondary authentication) before access is granted
  • FR-035: Which scopes require 2FA MUST be configurable without code changes
  • FR-036: System MUST challenge users with 2FA verification when accessing endpoints protected by 2FA-required scopes
  • FR-037: System MUST deny access to 2FA-protected scopes when valid 2FA verification is not provided
  • FR-038: System MUST apply rate limiting to 2FA verification attempts to prevent brute force attacks on verification codes

Non-Functional Requirements

  • NFR-001: System MUST support up to 500 concurrent authenticated users without performance degradation
  • NFR-002: Authentication requests MUST complete within 2 seconds under normal load conditions
  • NFR-003: Token refresh operations MUST complete within 500 milliseconds
  • NFR-004: System MUST maintain authentication service availability of 99.9% (excluding planned maintenance)
  • NFR-005: Rate limiting thresholds for authentication endpoints MUST be configurable without code changes
  • NFR-006: "Remember me" persistent cookie duration MUST be configurable without code changes

Key Entities

  • User: Represents an individual with access to the platform. Attributes include identity information (email, name), role type (organiser, sponsor, administrator), account status (active, deactivated), and credential information. Relationships to events, organisations, and authentication history.

  • Session: Represents metadata tracking for an active authenticated period. Used for audit logging and "active sessions" UI, NOT for storing authentication state (which lives in client-side tokens for stateless API design). Attributes include session identifier, creation time, last activity time, expiration time, user association, device/location information (IP address, user agent). Enables users to view where they're logged in and revoke specific sessions.

  • Authentication Credential: Represents the means by which a user proves their identity. Attributes include credential type (password with complexity requirements, or passwordless verification token), verification status, creation date, and last updated date. Relationship to user account.

  • Verification Token: Represents a time-limited token for email-based verification. Attributes include token code, associated email address, token purpose (passwordless login, 2FA verification, or password reset), expiration time, usage status (used/unused), and creation timestamp. Used for passwordless authentication (primary) and email-based 2FA fallback (secondary).

  • Authentication Event: Represents a security audit record of authentication activity. Attributes include event type (login attempt, successful login, logout, password reset), timestamp, user identifier, source information (IP address, device type), and outcome (success or failure reason).

  • API Client: Represents a third-party application authorized to access the API. Attributes include client identifier, client name, approved permission scopes (granular resource:action format), authorization status, creation date, and last used date. Relationship to authorizing user and issued tokens.

  • Permission Scope: Represents a specific permission for API access. Attributes include scope identifier (e.g., "events:read", "stands:write"), resource type, action type (read, write, delete), description, and 2FA requirement flag (configurable). Used to control third-party application access at granular level.

  • 2FA Configuration: Represents a user's two-factor authentication setup. Attributes include user association, authenticator type (TOTP app or email fallback), secret key (for TOTP), enabled status, setup date, and last used date. Relationship to user account.

  • 2FA Verification Code: Represents a time-limited verification code for 2FA challenges. Attributes include code value, associated user, generation timestamp, expiration time, usage status (used/unused), and verification method (authenticator app or email). Used for scope-based 2FA enforcement.

Success Criteria

Measurable Outcomes

  • SC-001: Users can complete login and access their dashboard in under 2 seconds with valid credentials
  • SC-002: System handles 500 concurrent authenticated users without performance degradation or failed authentication requests
  • SC-003: Password reset requests complete within 3 seconds and reset emails arrive within 1 minute
  • SC-004: 95% of authentication requests complete successfully on first attempt for users with valid credentials
  • SC-005: Token refresh operations complete within 500 milliseconds, enabling seamless session continuation
  • SC-006: Authentication service maintains 99.9% uptime measured across a calendar month (excluding planned maintenance)
  • SC-007: Users successfully authenticate across multiple devices simultaneously without conflicts or session interference
  • SC-008: Zero unauthorized access incidents due to token compromise, brute force attacks, or session hijacking
  • SC-009: Users who enable "remember me" remain authenticated for the configured duration (default 30 days) across browser restarts
  • SC-010: Rate limiting successfully prevents brute force attacks by limiting authentication attempts to configured thresholds without impacting legitimate users