User Management
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: User accounts, authentication, sessions, and role-based access control Domain: USERMGMT
Statement
The system shall provide complete user lifecycle management including account creation, authentication, session control, and role-based access enforcement.
This domain covers user administration (CRUD operations, MFA, password management), authentication via native credentials or federated SAML providers through AWS Cognito, single-device session enforcement with inactivity timeout, and a five-tier role hierarchy (Junior, Senior, Client-Admin, Manager, Super Admin) that determines screen and feature access across the application.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Native Authentication | Login using username/password credentials stored in the system |
| Federated Authentication | Login using external identity provider credentials via SAML |
| MFA | Multi-Factor Authentication requiring TOTP verification after password |
| HOTP/TOTP | Time-based One-Time Password algorithm for second-factor authentication |
| Junior User | Base role with access to Run Files, Reports, Audits, and Upload Runs |
| Senior User | Extended role with Junior capabilities plus Westgard settings management |
| Client-Admin User | Administrative role with User Management and Audits access only |
| Manager User | Multi-site oversight role with read-only access across sites |
| Super Admin | System administrator with full access; cannot be modified by Client-Admin |
| Visible Sites | Sites a user has been granted access to view and interact with |
Functional Requirements
User Administration (REQ-USERMGMT-001 through REQ-USERMGMT-008)
FR-USERMGMT-001 Display User Accounts
The system shall display all user accounts with their associated attributes for administrative review.
Acceptance Criteria:
Display:
- The system shall display user account information including: username, email, role, password status, MFA status, email verification status, enabled status
- Each user account shall be represented as a distinct entry
- The system shall indicate which accounts can be deleted
Trace: Source: 3.0.0-User Management (Rows 1, 2, 35, 37) | Jira: BT-2422, BT-2659 | Tests: BT-404, BT-1873
FR-USERMGMT-002 Modify User Role
The system shall allow administrators to change a user's assigned role.
Acceptance Criteria:
Role Selection:
- The system shall present available roles for selection
- Role changes shall require explicit confirmation before applying
- The system shall prevent role changes without user confirmation
Multi-Site Restriction:
- Role modification shall be restricted when user has multiple visible sites
- The system shall disable role modification when user has multiple visible sites
Assumptions:
- User has single visible site (multi-site users cannot have role changed)
Trace: Source: 3.0.0-User Management (Rows 3-7), 3.0.0-User Management - Consider Visible Sites (Row 1) | Jira: BT-2659, BT-4006 | Tests: BT-444
FR-USERMGMT-003 Reset User Password
The system shall allow administrators to reset a user's password while enforcing password complexity requirements.
Acceptance Criteria:
Password Entry:
- Password changes shall require entry and confirmation of new password
- The system shall validate password against complexity requirements before accepting
- The system shall require confirmation password to match new password
Submission Control:
- The system shall prevent password submission until all criteria are satisfied
- The system shall prevent copy/paste between password and confirmation fields
Error Handling:
- Password does not meet complexity requirements: The system shall display specific criteria not met
- Confirmation does not match password: The system shall display "Confirmation does not match" message
Trace: Source: 3.0.0-User Management (Rows 8-15) | Jira: BT-64 | Tests: BT-409
FR-USERMGMT-004 Configure User MFA
The system shall allow administrators to configure multi-factor authentication for user accounts.
Acceptance Criteria:
MFA Setup:
- The system shall generate and display HOTP secret for MFA setup
- The system shall provide QR code encoding of the HOTP secret
- The system shall allow copying HOTP secret to clipboard
Verification:
- The system shall verify TOTP code before completing MFA setup
- MFA setup shall require successful TOTP verification to complete
Error Handling:
- Invalid TOTP code entered: The system shall display verification error message
- Empty TOTP code submitted: The system shall prevent submission
Trace: Source: 3.0.0-User Management (Rows 16-20) | Jira: BT-2619 | Tests: BT-442
FR-USERMGMT-005 Request Email Verification
The system shall allow administrators to trigger email verification for user accounts.
Acceptance Criteria:
- The system shall send verification email to user's registered email address
- The system shall indicate when email has been verified
Error Handling:
- Email delivery fails: The system shall notify administrator of delivery failure
Trace: Source: 3.0.0-User Management (Rows 21-22) | Jira: BT-3166 | Tests: BT-424
FR-USERMGMT-006 Control User Account Status
The system shall allow administrators to enable or disable user accounts, controlling their ability to access the system.
Acceptance Criteria:
Status Toggle:
- The system shall allow toggling user enabled/disabled status
- Disabled users shall not be able to authenticate
- User deletion shall only be available for disabled accounts
Session Termination:
- Disabling a user shall immediately terminate all active sessions for that user
- The system shall allow administrators to force logout users from identity provider
- Session termination on disable shall use Cognito global sign-out
Trace: Source: 3.0.0-User Management (Rows 23-24, 38-39), 3.0.0-Login 2.6.x - 3.x (Row 13) | Jira: BT-3202 | Tests: BT-425
FR-USERMGMT-007 Delete User Account
The system shall allow administrators to permanently remove user accounts from the system.
Acceptance Criteria:
- User deletion shall only be available for disabled accounts
- Deletion shall permanently remove the user account and associated data
Assumptions:
- User account has been disabled prior to deletion attempt
Trace: Source: 3.0.0-User Management (Row 25) | Jira: BT-3958 | Tests: BT-427
FR-USERMGMT-008 Create User Account
The system shall allow administrators to create new user accounts with required profile information and credentials.
Acceptance Criteria:
Required Fields:
- User creation shall require: username, email, password, and role assignment
- Username shall accept any characters with minimum 1 character
- Email shall be validated for correct format
- Password shall meet complexity requirements
Uniqueness:
- Email shall be unique across all user accounts
- Display name shall be unique across all user accounts
Defaults and Notifications:
- New accounts shall default to Junior role
- The system shall send notification emails upon account creation
- The system shall send two notification emails upon account creation
- The system shall initiate MFA setup after account creation
Error Handling:
- Email already exists: The system shall display "Email already in use" message
- Display name already exists: The system shall display "Display name already in use" message
- Invalid email format: The system shall display email format requirements
- Password does not meet requirements: The system shall display unmet criteria
Trace: Source: 3.0.0-User Management (Rows 26-34, 40) | Jira: BT-2659 | Tests: BT-430
Authentication (REQ-USERMGMT-009 through REQ-USERMGMT-012)
FR-USERMGMT-009 Authenticate Users
The system shall authenticate users via native credentials or federated identity providers before granting system access.
Acceptance Criteria:
Native Authentication:
- The system shall accept authentication via username and password (native)
- Authentication shall require valid credentials before granting access
- The system shall require password change on first login
- The system shall require password change after administrator password reset
Federated Authentication:
- The system shall accept authentication via SAML identity provider (federated)
- First-time federated users shall be automatically provisioned with Senior role
- Federated authentication may use group attribute to determine user role
- Federated authentication shall use AWS Cognito as identity broker
- SAML integration shall follow standard SAML 2.0 protocol
MFA:
- The system shall require MFA verification when MFA is enabled for user
Configuration:
- The system shall support configuration to disable native authentication
Error Handling:
- Invalid native credentials: The system shall display authentication error message
- Invalid federated credentials: The system shall display authentication error message
- MFA verification fails: The system shall display verification error and allow retry
Trace: Source: 3.0.0-Login 2.6.x - 3.x (Rows 1-5, 8, 11, 19), 3.0.0-SAML Access (Rows 1-6) | Jira: BT-2399, BT-54, BT-2488, BT-362, BT-805, BT-636 | Tests: BT-942, BT-943, BT-929 | Related: REQ-USERMGMT-010 (consolidated)
FR-USERMGMT-010 Verify Email on First Login
The system shall require new users to verify their email address before accessing the application.
Acceptance Criteria:
- Email verification shall be required on first login
- Users shall not be able to proceed to application until email is verified
Trace: Source: 3.0.0-Login 2.6.x - 3.x (Row 6) | Jira: BT-1621 | Tests: BT-1986
FR-USERMGMT-011 Manage User Sessions
The system shall manage user sessions including single-device enforcement and inactivity timeout.
Acceptance Criteria:
Single-Device Enforcement:
- Users shall be restricted to one active session at a time
- New session login shall terminate existing sessions for that user
Inactivity Management:
- The system shall automatically terminate sessions after configured inactivity period
- The system shall notify users when session is terminated
- The system shall distinguish between timeout types (inactivity vs. session expiry)
Trace: Source: 3.0.0-Login 2.6.x - 3.x (Rows 9-10, 14-15) | Jira: BT-3213 | Tests: BT-3839
FR-USERMGMT-012 Enforce Access Control Policies
The system shall enforce access control policies based on site configuration and IP restrictions.
Acceptance Criteria:
Site-Based Access:
- When no site restriction is configured, all authenticated users shall have access
- When site restriction is configured, only users with access to specified site shall be permitted
- Multiple site codes may be configured as aliases for the same site
IP-Based Access:
- When IP whitelisting is configured, only requests from specified IPs shall be permitted
- Access control configuration may require Cognito group membership
Error Handling:
- User lacks site access: The system shall deny login and display access restriction message
- Request from non-whitelisted IP: The system shall deny access
Trace: Source: 3.0.0-Login 2.6.x - 3.x (Rows 12, 16-18, 20-21) | Jira: BT-3370, BT-3648 | Tests: BT-3840, BT-3841 | Related: REQ-USERMGMT-013, REQ-USERMGMT-014 (consolidated)
Role-Based Access Control (REQ-USERMGMT-013 through REQ-USERMGMT-014)
FR-USERMGMT-013 Enforce Role-Based Access Control
The system shall restrict screen and feature access based on user's assigned role.
Acceptance Criteria:
Junior Role:
- Junior users shall have access to: Run Files, Reports, Audits, Upload Runs screens
Senior Role:
- Senior users shall have all Junior access plus Westgard settings management
Client-Admin Role:
- Client-Admin users shall have access to: User Management, Audits screens only
- Client-Admin users shall not be able to upload runs
- Client-Admin users shall not be able to modify Super Admin accounts
Manager Role:
- Manager users shall have multi-site read access to: Run Files, Reports, Audits
- Manager users shall not be able to upload runs
- Manager users shall have read-only access (no result management or settings editing)
- Manager users shall be able to add comments and create alerts
UI Restrictions:
- Junior, Senior, and Client-Admin users shall not be able to see version information
Error Handling:
- User attempts unauthorized screen access: The system shall redirect or display access denied
- User attempts unauthorized action: The system shall reject with Unauthorized error
Trace: Source: 3.0.0-User Types Summary (Rows 1-8), 3.0.0-Junior user (Rows 1-11), 3.0.0-Senior user (Rows 1-12), 3.0.0-Client-Admin user (Rows 1-6), 3.0.0-Manager user (Rows 2, 10, 19-20) | Jira: BT-3035 | Tests: BT-3738 | Related: REQ-USERMGMT-016, REQ-USERMGMT-017 (consolidated)
FR-USERMGMT-014 Provide Multi-Site Data Access
The system shall provide Manager users with the ability to view and filter data across multiple sites.
Acceptance Criteria:
Multi-Site Filtering:
- Multi-site filtering shall be available on applicable screens
- Site information shall be visible in data displays and exports
Visualization:
- Report visualizations shall distinguish data by site
- Export data shall include site attribution
Assumptions:
- User has Manager role
- User has access to multiple sites
Trace: Source: 3.0.0-Manager user (Rows 1-9, 11-18) | Jira: BT-3035 | Tests: BT-3738
Security (REQ-USERMGMT-015 through REQ-USERMGMT-016)
FR-USERMGMT-015 Enforce Authentication Security Policies
The system shall enforce security policies for authentication credentials and access attempts.
Acceptance Criteria:
Username Requirements:
- Non-federated usernames shall be at least 1 character
Password Requirements:
- Non-federated passwords shall meet complexity requirements (minimum 10 characters, 1 uppercase, 1 lowercase, 1 number)
- Users shall not be able to reuse their 5 most recent passwords
- Users shall be required to change password every 90 days
Access Limits:
- System shall support up to 30 concurrent users
- Account shall be locked after 5 incorrect login attempts
Audit:
- Login events shall be recorded in audit log
- Logout events shall be recorded in audit log
Trace: Source: 3.0.0-Login NFRs (Rows 1-7), 3.0.0-Login Audit Requirements (Rows 1-2) | Jira: BT-3784, BT-3785 | Tests: [Pending]
FR-USERMGMT-016 Ensure System Readiness Before Login
The system shall prevent login attempts until backend services are available and ready to process requests.
Acceptance Criteria:
Availability Check:
- The system shall verify backend service availability before enabling login
- The system shall prevent authentication attempts while backend services are initializing
User Feedback:
- The system shall indicate to users when the system is not yet ready
- The system shall automatically enable login once backend services are available
Error Handling:
- Backend services unavailable: The system shall display a loading indicator and prevent login attempts
- Backend services timeout during initialization: The system shall display an error message and provide retry option
Trace: Source: 3.0.0-Login Page - Loading Indicator (Rows 1-2) | Jira: [TBD] | Tests: [Pending]
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
session_inactivity_timeout_minutes | 30 | Minutes of inactivity before automatic logout | REQ-USERMGMT-011 |
prevent_native_login | false | When true, hides native login form | REQ-USERMGMT-009 |
require_cognito_group | false | When true, requires Cognito group for access | REQ-USERMGMT-012 |
block_unauthorized_ip | false | When true, enforces IP whitelist | REQ-USERMGMT-012 |
password_expiry_days | 90 | Days until password change required | REQ-USERMGMT-015 |
password_history_count | 5 | Number of previous passwords that cannot be reused | REQ-USERMGMT-015 |
max_login_attempts | 5 | Failed attempts before account lockout | REQ-USERMGMT-015 |
max_concurrent_users | 30 | Maximum simultaneous authenticated users | REQ-USERMGMT-015 |
default_new_user_role | Junior | Default role assigned to new accounts | REQ-USERMGMT-008 |
default_saml_user_role | Senior | Default role for auto-provisioned SAML users | REQ-USERMGMT-009 |
Assumptions
- Users accessing User Management screens have Client-Admin or Super Admin role
- AWS Cognito is configured and available for authentication services
- SMTP service is configured for email verification and notification delivery
- At least one site is configured in the system
- Password complexity rules are enforced at the Cognito level
[REVIEW REQUIRED] Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME.
UI Notes (Illustrative)
FR-USERMGMT-001 UI Specifications
- Page title displays "User management"
- Table displays columns: Username, Email, User Type, Change Password, MFA, Email Status, User Enabled, Delete
- Delete column header includes info helper icon with tooltip "Disable user to delete"
- Each row represents one user account
FR-USERMGMT-002 UI Specifications
- Role selection presented in dialog
- Apply button enabled only when different role selected
- Apply button disabled if role changed back to current value
- Cancel button closes dialog without changes
FR-USERMGMT-003 UI Specifications
- Dialog displays Enter Password and Confirm Password fields
- Password criteria prompt appears when typing begins
- Criteria prompt removed when all requirements met
- "Confirmation does not match" prompt when passwords differ
- Copy/paste blocked between password fields
- Save button disabled until all validation passes
FR-USERMGMT-004 UI Specifications
- Dialog displays HOTP secret with QR code
- Copy button with clipboard confirmation
- Verify TOTP Code button disabled when field empty
- Success closes dialog; failure shows error message
FR-USERMGMT-005 UI Specifications
- Send verification button triggers email
- "Verified" text replaces button when email verified
FR-USERMGMT-006 UI Specifications
- User Enabled toggle switch
- Delete button disabled while user enabled
FR-USERMGMT-008 UI Specifications
- Dialog with fields: Username, Email, Password, Confirm Password, User Type
- User type dropdown defaults to Junior
- Create button enabled only when all fields valid
- Setup MFA dialog displayed after successful creation
FR-USERMGMT-009 UI Specifications
- Sign in button enabled only when both username and password entered
- SAML login button displayed on login page
- MFA screen displayed after correct credentials when MFA enabled
- Force password change screen displayed when required
- Error toast displayed for incorrect credentials
FR-USERMGMT-013 UI Specifications
- Version information hidden for Junior, Senior, and Client-Admin users
FR-USERMGMT-014 UI Specifications
- Site filter available as multi-select dropdown on applicable screens
- Site column visible in data tables
- Graph legends include site information
- Different colors used for each site in visualizations
FR-USERMGMT-016 UI Specifications
- Loading indicator displayed during database wakeup
- Login buttons disabled until loading complete
General Dialog Patterns
- Dialogs open on action button click
- Apply/Save button enabled only when changes made
- Cancel button closes without saving
- Confirmation prompts displayed after successful actions
Form Validation Patterns
- Validation prompts appear when user starts typing
- Prompts removed when criteria met
- Submit buttons remain disabled until all validation passes
Implementation (Illustrative)
| Component | Location | Description |
|---|---|---|
| Controller | app/Http/Controllers/Auth/LoginController.php | Native login flow (username/password) |
| Controller | app/Http/Controllers/Auth/SamlLoginController.php | SAML SSO federated login |
| Controller | app/Http/Controllers/Auth/ResetPasswordController.php | Forgot password flow with Cognito confirmation |
| Controller | app/Http/Controllers/Auth/ChangePasswordController.php | Mandatory password change (first login/admin reset) |
| Controller | app/Http/Controllers/Auth/MfaController.php | MFA setup and TOTP verification |
| Controller | app/Http/Controllers/UsersController.php | User CRUD operations (list, create, update, delete) |
| Controller | app/Http/Controllers/BlockedUsersController.php | User enable/disable operations |
| Trait | app/Http/Controllers/Auth/HandleAuthenticated.php | Shared auth logic (MFA challenge, session, access control) |
| Service | app/Support/CognitoAuthenticator.php | Cognito adminInitiateAuth wrapper |
| Service | app/CognitoUserManager.php | Cognito user lifecycle management |
| Model | app/CognitoUser.php | Cognito user attribute wrapper |
| Action | app/Actions/UserManagement/StoreUserAction.php | Create user with Cognito sync |
| Action | app/Actions/UserManagement/UpdateUserTypeAction.php | Update user role with validation |
| Action | app/Actions/Users/BlockUserAction.php | Disable user and revoke sessions |
| Action | app/Actions/Users/UnblockUserAction.php | Enable previously disabled user |
| Action | app/Actions/Users/UpdateUserAction.php | Update user profile attributes |
| Middleware | app/Http/Middleware/Authenticate.php | Auth enforcement and login redirect |
| Event | app/Events/UserLoggedIn.php | Login audit event |
| Event | app/Events/UserLoggedOut.php | Logout audit event |
| Event | app/Events/UserAccountCreated.php | Account creation audit event |
| Event | app/Events/UserAccountDeleted.php | Account deletion audit event |
| Event | app/Events/UserAccountDisabled.php | Account disable audit event |
| Event | app/Events/UserAccountEnabled.php | Account enable audit event |
| Event | app/Events/PasswordChanged.php | Password change audit event |
| Event | app/Events/UserAssociatedWithRole.php | Role assignment audit event |
Frontend Implementation (Illustrative)
| Component Type | Location |
|---|---|
| View | views/Users.vue |
| View | views/ChangePassword.vue |
| Components | components/users/ |
| Store | store/modules/auth.js |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-USERMGMT-001 | Display User Accounts | Test | UsersController | BT-404, BT-1873 | Draft |
| REQ-USERMGMT-002 | Modify User Role | Test | UpdateUserTypeAction | BT-444 | Draft |
| REQ-USERMGMT-003 | Reset User Password | Test | ResetPasswordController | BT-409 | Draft |
| REQ-USERMGMT-004 | Configure User MFA | Test | MfaController | BT-442 | Draft |
| REQ-USERMGMT-005 | Request Email Verification | Test | CognitoUserManager | BT-424 | Draft |
| REQ-USERMGMT-006 | Control User Account Status | Test | BlockUserAction, UnblockUserAction | BT-425 | Draft |
| REQ-USERMGMT-007 | Delete User Account | Test | UsersController | BT-427 | Draft |
| REQ-USERMGMT-008 | Create User Account | Test | StoreUserAction | BT-430 | Draft |
| REQ-USERMGMT-009 | Authenticate Users | Test | LoginController, SamlLoginController | BT-942, BT-943, BT-929 | Draft |
| REQ-USERMGMT-010 | Verify Email on First Login | Test | HandleAuthenticated | BT-1986 | Draft |
| REQ-USERMGMT-011 | Manage User Sessions | Test | HandleAuthenticated | BT-3839 | Draft |
| REQ-USERMGMT-012 | Enforce Access Control Policies | Test | HandleAuthenticated | BT-3840, BT-3841 | Draft |
| REQ-USERMGMT-013 | Enforce Role-Based Access Control | Test | Middleware, HandleAuthenticated | BT-3738 | Draft |
| REQ-USERMGMT-014 | Provide Multi-Site Data Access | Test | Frontend filters | BT-3738 | Draft |
| REQ-USERMGMT-015 | Enforce Authentication Security Policies | Test | Cognito, CognitoAuthenticator | [Pending] | Draft |
| REQ-USERMGMT-016 | Ensure System Readiness Before Login | Test | Frontend, Health checks | [Pending] | Draft |
Notes
- Federated authentication integration uses AWS Cognito as identity broker
- Password complexity requirements enforced at Cognito level in addition to application level
- Session management coordinated with Cognito for global sign-out capabilities
- Multi-site functionality is specific to Manager role; other roles operate within single site context
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | Assumptions inferred from context, not explicitly stated in source. Confirm accuracy with SME. | Assumptions | @SME-TBD | TBD |
Acceptance Tests
Test: REQ-USERMGMT-001
Test: Display user list
Given: User logged in as administrator
When: Navigate to User Management screen
Then: User list is displayed with account information
And: Each user account appears as distinct entry
Test: REQ-USERMGMT-002
Test: Modify role for single-site user
Given: User on User Management screen
And: Target user has single visible site
When: Administrator initiates role change
Then: Available roles are presented for selection
When: Administrator confirms role selection
Then: Role is applied to user account
When: Administrator cancels without selecting
Then: No changes are made to user role
Test: Block role change for multi-site user
Given: Target user has multiple visible sites
When: Administrator attempts role change
Then: Role modification is not available
Test: REQ-USERMGMT-003
Test: Reset password with validation
Given: Administrator initiates password reset for user
When: New password meeting complexity requirements is entered
And: Confirmation matches new password
Then: Password is reset successfully
When: Password does not meet complexity requirements
Then: System displays unmet criteria
When: Confirmation does not match password
Then: System displays mismatch error
Test: REQ-USERMGMT-004
Test: Configure MFA
Given: Administrator initiates MFA setup for user
Then: HOTP secret is generated and displayed
And: QR code encoding is provided
When: Valid TOTP code is entered
Then: MFA setup completes successfully
When: Invalid TOTP code is entered
Then: Error is displayed and retry is available
Test: REQ-USERMGMT-005
Test: Email verification flow
Given: User has unverified email
When: Administrator triggers verification
Then: Verification email is sent to user
When: User completes email verification
Then: Email status shows as verified
Test: REQ-USERMGMT-006
Test: Disable user account
Given: User account is enabled
When: Administrator disables user
Then: User account status is disabled
And: All active sessions are terminated
Given: User account is disabled
When: User attempts to authenticate
Then: Authentication is rejected
Test: REQ-USERMGMT-007
Test: Delete user account
Given: User account is disabled
When: Administrator deletes user
Then: User account is permanently removed
Given: User account is enabled
When: Administrator attempts to delete
Then: Deletion is not available
Test: REQ-USERMGMT-008
Test: Create user account
Given: Administrator initiates user creation
When: All required fields are provided with valid values
And: Email is unique across system
And: Display name is unique across system
Then: User account is created with Junior role
And: Notification emails are sent
And: MFA setup is initiated
When: Email already exists
Then: Error indicates email in use
When: Display name already exists
Then: Error indicates name in use
Test: REQ-USERMGMT-009
Test: Native authentication
Given: User has valid native credentials
When: User submits credentials
Then: User is authenticated
Given: User has MFA enabled
When: User enters valid credentials
Then: MFA verification is required
When: MFA verification succeeds
Then: User is granted access
Test: Federated authentication
Given: User authenticates via federated provider
And: User does not exist in system
When: Authentication succeeds
Then: User is auto-provisioned with Senior role
Test: REQ-USERMGMT-010
Test: First login email verification
Given: New user logging in for first time
When: Authentication succeeds
Then: Email verification is required
When: Email is not verified
Then: User cannot access application
When: Email is verified
Then: User can proceed to application
Test: REQ-USERMGMT-011
Test: Single device enforcement
Given: User logged in on Device A
When: User logs in on Device B
Then: Session on Device A is terminated
Test: Inactivity timeout
Given: User is logged in
When: User is inactive for configured timeout period
Then: Session is automatically terminated
And: User is notified of session termination
Test: REQ-USERMGMT-012
Test: Site-based access control
Given: No site restriction configured
When: Authenticated user attempts access
Then: Access is granted
Given: Site restriction configured
And: User has access to specified site
When: User attempts access
Then: Access is granted
Given: Site restriction configured
And: User lacks access to specified site
When: User attempts access
Then: Access is denied
Test: IP-based access control
Given: IP whitelist configured
And: Request from non-whitelisted IP
When: Access attempted
Then: Access is denied
Test: REQ-USERMGMT-013
Test: Junior role access
Given: User logged in as Junior
Then: Run Files, Reports, Audits, Upload Runs are accessible
And: User Management is not accessible
Test: Senior role access
Given: User logged in as Senior
Then: All Junior capabilities are available
And: Westgard settings management is available
Test: Client-Admin role access
Given: User logged in as Client-Admin
Then: User Management, Audits are accessible
And: Run Files, Reports, Upload Runs are not accessible
Test: Manager role access
Given: User logged in as Manager
Then: Multi-site Run Files, Reports, Audits are accessible
And: Comments and alerts can be created
And: Result management and settings editing are not available
Test: REQ-USERMGMT-014
Test: Multi-site data access
Given: User logged in as Manager with multiple site access
When: Accessing data screens
Then: Site filtering is available
And: Site information is visible in displays
And: Visualizations distinguish data by site
Test: REQ-USERMGMT-015
Test: Password complexity
Given: User creating password
When: Password does not meet complexity requirements
Then: Password is rejected
Test: Password history
Given: User changing password
When: New password matches recent password
Then: Password is rejected
Test: Password expiry
Given: User has not changed password in 90 days
When: User logs in
Then: Password change is required
Test: Account lockout
Given: 5 incorrect login attempts made
When: 6th attempt is made
Then: Account is locked
Test: REQ-USERMGMT-016
Test: Backend initialization
Given: Backend services are initializing
When: User navigates to login page
Then: Login functionality is disabled
And: System indicates it is not yet ready
Given: Backend services complete initialization
When: System detects readiness
Then: Login functionality is enabled automatically
Test: Backend unavailable
Given: Backend services are unavailable
When: User navigates to login page
Then: Login functionality is disabled
And: Loading indicator is displayed
Given: Backend services timeout during initialization
When: Timeout threshold is reached
Then: Error message is displayed
And: Retry option is provided
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Architecture | Amazon Cognito authentication, DynamoDB session management, Amazon SES email services, Aurora Serverless cold start handling |
| SDD Security | Authentication and Authorization flow, Cognito-based JWT authentication, MFA verification, session management, RBAC enforcement |
| SDD Deployment Operations | Cognito User Pool setup, SAML provider configuration, session management infrastructure |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into Acceptance Criteria (no standalone Refinements section)
- Traceability matrix is complete
Reviewer Notes
Consolidation: REQ-USERMGMT-009 (Authenticate Users)
The following items from the source were consolidated into a single authentication requirement:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-USERMGMT-009 (Personal credentials login) | 3.0.0-Login 2.6.x - 3.x (Rows 1-3, 5, 8) | Merged -> REQ-USERMGMT-009 |
| REQ-USERMGMT-010 (Federated credentials login) | 3.0.0-Login 2.6.x - 3.x (Row 4, 11, 19), 3.0.0-SAML Access (Rows 1-6) | Merged -> REQ-USERMGMT-009 |
Rationale: Native and federated authentication are variants of a single "Authenticate Users" capability. The system responsibility is to verify identity; the method (native vs. federated) is a refinement.
Reversibility: To restore original structure, reference:
- Source:
output/pilot/restructured/user-management.md - Confluence: 3.0.0-Login 2.6.x - 3.x, 3.0.0-SAML Access
Consolidation: REQ-USERMGMT-012 (Enforce Access Control Policies)
The following items from the source were consolidated into a single access control requirement:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-USERMGMT-013 (Site-based access control) | 3.0.0-Login 2.6.x - 3.x (Rows 16-18, 21) | Merged -> REQ-USERMGMT-012 |
| REQ-USERMGMT-014 (IP whitelist access control) | 3.0.0-Login 2.6.x - 3.x (Rows 12, 20) | Merged -> REQ-USERMGMT-012 |
Rationale: Site-based and IP-based access control are variants of a single "Enforce Access Policies" capability. Both represent configurable access restrictions.
Reversibility: To restore original structure, reference:
- Source:
output/pilot/restructured/user-management.md - Confluence: 3.0.0-Login 2.6.x - 3.x (Rows 12, 16-21)
Consolidation: REQ-USERMGMT-013 (Enforce Role-Based Access Control)
The following items from the source were consolidated into a single RBAC requirement:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-USERMGMT-016 (Screen access by role) | 3.0.0-User Types Summary, Junior/Senior/Client-Admin/Manager user pages | Merged -> REQ-USERMGMT-013 |
| REQ-USERMGMT-017 (Feature access by role) | 3.0.0-User Types Summary, Junior/Senior/Client-Admin/Manager user pages | Merged -> REQ-USERMGMT-013 |
Rationale: Screen access and feature access are aspects of a single "Enforce RBAC" capability. Both describe permission restrictions based on role.
Reversibility: To restore original structure, reference:
- Source:
output/pilot/restructured/user-management.md - Confluence: 3.0.0-User Types Summary, 3.0.0-Junior user, 3.0.0-Senior user, 3.0.0-Client-Admin user, 3.0.0-Manager user
Promotion: REQ-USERMGMT-016 (System Readiness)
| Original Item | Source Reference | Disposition |
|---|---|---|
| Loading indicator during login page initialization | 3.0.0-Login Page - Loading Indicator (Rows 1-2) | UI behavior demoted; underlying capability promoted to REQ-USERMGMT-016 |
Rationale: The loading indicator itself is a UI behavior (demoted to UI Detail section). However, the underlying capability - preventing login attempts before backend services are available - is a system behavior that warrants a requirement. REQ-USERMGMT-016 was added to capture this capability.
Resolution: The implicit requirement "The system shall prevent login attempts before backend services are available" has been added as REQ-USERMGMT-016.
ID Renumbering Summary
Due to consolidations, the SRS uses the following ID mapping:
| SRS ID | Original Source ID(s) |
|---|---|
| REQ-USERMGMT-001 | REQ-USERMGMT-001 |
| REQ-USERMGMT-002 | REQ-USERMGMT-002 |
| REQ-USERMGMT-003 | REQ-USERMGMT-003 |
| REQ-USERMGMT-004 | REQ-USERMGMT-004 |
| REQ-USERMGMT-005 | REQ-USERMGMT-005 |
| REQ-USERMGMT-006 | REQ-USERMGMT-006 |
| REQ-USERMGMT-007 | REQ-USERMGMT-007 |
| REQ-USERMGMT-008 | REQ-USERMGMT-008 |
| REQ-USERMGMT-009 | REQ-USERMGMT-009, REQ-USERMGMT-010 |
| REQ-USERMGMT-010 | REQ-USERMGMT-011 |
| REQ-USERMGMT-011 | REQ-USERMGMT-012 |
| REQ-USERMGMT-012 | REQ-USERMGMT-013, REQ-USERMGMT-014 |
| REQ-USERMGMT-013 | REQ-USERMGMT-016, REQ-USERMGMT-017 |
| REQ-USERMGMT-014 | REQ-USERMGMT-018 |
| REQ-USERMGMT-015 | NFR-USERMGMT-001 |
| REQ-USERMGMT-016 | (promoted from demoted Loading Indicator) |