Authentication & Tenant Administration Use Cases

This document describes use cases for authentication, multi-tenancy, user management, tagging configuration, and system administration.

Actors

UC-AUTH-01: User Login

Primary Actor: Employee, Manager, Tenant Admin

Preconditions

• User has an active account
• User knows their credentials

Main Flow

1. User navigates to login page
2. User enters email and password
3. System validates credentials
4. If user belongs to multiple tenants, system shows tenant selector
5. User selects tenant (or auto-selects if only one)
6. System creates session and redirects to dashboard

Alternative Flows

A1: Invalid Credentials

1. System displays "Invalid email or password" error
2. User can retry (max 5 attempts)

A2: Account Locked

1. After 5 failed attempts, account is locked for 15 minutes
2. System displays lock message with unlock time

A3: Password Reset Required

1. If password expired, system redirects to password reset
2. User must set new password before continuing

Postconditions

• User is authenticated
• Session is created with tenant context
• Audit log records login event

UC-AUTH-02: Tenant Admin Creates Organization

Primary Actor: Tenant Admin (initial setup)

Preconditions

• User has signed up for the platform
• User has verified their email

Main Flow

1. User completes signup form
2. System creates user account
3. User enters company details:
   • Company name
   • Industry
   • Size (employee count range)
   • Country/timezone
4. System creates tenant with default configuration:
   • Default roles (Admin, Manager, Employee)
   • Default leave types (Vacation, Sick, Personal)
   • Default permissions matrix
5. User is assigned Tenant Admin role
6. System redirects to onboarding wizard

Alternative Flows

A1: Company Name Already Exists

1. System suggests adding identifier (e.g., "Acme Inc - NYC")
2. User modifies company name

Postconditions

• New tenant is created and active
• User is Tenant Admin of the new tenant
• Default configuration is applied
• Welcome email sent with getting started guide

UC-AUTH-03: Tenant Admin Invites Users

Primary Actor: Tenant Admin

Preconditions

• Tenant Admin is authenticated
• User to invite does not exist in tenant

Main Flow

1. Tenant Admin navigates to User Management
2. Clicks "Invite User"
3. Enters user details:
   • Email address
   • First name, Last name
   • Role (Admin, Manager, or Employee)
   • Department (optional)
4. System validates email is not already in tenant
5. System sends invitation email with secure link
6. Invitation appears in pending invitations list

Alternative Flows

A1: Email Already Exists in Tenant

1. System displays "User already exists" error
2. Offers to navigate to existing user's profile

A2: Email Exists in Different Tenant

1. System creates invitation (user can belong to multiple tenants)
2. When user accepts, they can switch between tenants

A3: Invitation Expires

1. Link expires after 7 days
2. Tenant Admin can resend invitation

Postconditions

• Invitation record created with status PENDING
• Email sent to invitee
• Audit log records invitation

Business Rules

• Invitation links are single-use and expire after 7 days
• Users can be invited to multiple tenants

UC-AUTH-04: Tenant Admin Manages Users

Primary Actor: Tenant Admin

Preconditions

• Tenant Admin is authenticated
• Users exist in the tenant

Main Flow

1. Tenant Admin navigates to User Management
2. Views list of users with:
   • Name, email, role
   • Status (active, inactive, pending)
   • Last login date
3. Selects a user to manage
4. Can perform actions:
   • Edit user details
   • Change role
   • Reset password
   • Deactivate/reactivate account

Alternative Flows

A1: Cannot Deactivate Last Admin

1. System prevents deactivation
2. Displays "Cannot deactivate the last administrator"

A2: Deactivating User with Pending Approvals

1. System warns about pending items
2. Requires reassignment or confirmation to proceed

Postconditions

• User account updated
• Audit trail records all changes
• If deactivated, user's sessions are invalidated

Business Rules

• Must always have at least one active Tenant Admin
• Deactivated users retain data but cannot login
• Role changes take effect immediately

UC-AUTH-05: Tenant Admin System Dashboard

Primary Actor: Tenant Admin

Preconditions

• Tenant Admin is authenticated

Main Flow

1. Tenant Admin accesses Admin Dashboard
2. Views system metrics:
   • Total users (active, inactive, pending invitations)
   • Storage usage (documents, attachments)
   • Recent activity summary
   • Pending approvals count
3. Views quick actions:
   • Invite user
   • View pending invitations
   • Access settings
4. Views system health indicators:
   • API response times
   • Error rate (last 24 hours)

Alternative Flows

A1: High Error Rate Detected

1. Dashboard highlights warning
2. Links to error details and support contact

Postconditions

• Admin has overview of tenant health
• No data is modified (read-only view)

UC-AUTH-06: User Switches Tenant Context

Primary Actor: Employee (multi-tenant user)

Preconditions

• User belongs to multiple tenants
• User is authenticated

Main Flow

1. User clicks tenant selector in header
2. System displays list of available tenants
3. User selects different tenant
4. System switches context:
   • Updates session tenant ID
   • Refreshes navigation and permissions
   • Redirects to new tenant's dashboard
5. All data now filtered to selected tenant

Alternative Flows

A1: Tenant Access Revoked

1. If user was removed from tenant, it no longer appears
2. System handles gracefully if current tenant is revoked

Postconditions

• Session updated with new tenant context
• UI reflects new tenant's data and branding
• Audit log records context switch

UC-AUTH-07: Logout

Primary Actor: All users

Preconditions

• User is authenticated

Main Flow

1. User clicks Logout
2. System invalidates session
3. System clears local storage/cookies
4. User is redirected to login page

Alternative Flows

A1: Session Already Expired

1. User is already logged out
2. Redirect to login page without error

Postconditions

• Session is invalidated
• User must re-authenticate to access system
• Audit log records logout event

UC-AUTH-08: Tenant Admin Configures Tag Categories

Primary Actor: Tenant Admin

Preconditions

• Tenant Admin is authenticated
• Has access to system configuration

Main Flow

1. Tenant Admin navigates to Settings → Tags
2. Selects asset type to configure:
   • Employee
   • Document
   • Department
   • Goal
3. Views existing tags for that asset type
4. Creates new tag:
   • Name (unique within asset type)
   • Color (hex code or preset)
   • Description (optional)
5. Saves tag
6. Tag becomes available for assignment

Alternative Flows

A1: Tag Name Already Exists

1. System displays "Tag name already exists" error
2. User must choose unique name

A2: Editing Existing Tag

1. User selects existing tag
2. Can modify name, color, description
3. Changes apply to all tagged items

A3: Deleting Tag

1. User selects tag to delete
2. System warns about items currently using tag
3. On confirmation, tag is removed from all items

Postconditions

• Tag is created/updated/deleted
• Available for assignment to assets of that type
• Audit log records configuration change

Example Tags by Asset Type

UC-AUTH-09: Tenant Admin Manages Tag Permissions

Primary Actor: Tenant Admin

Preconditions

• Tenant Admin is authenticated
• Tags are configured for at least one asset type

Main Flow

1. Tenant Admin navigates to Settings → Tags → Permissions
2. For each asset type, configures who can:
   • Create tags: Admin-only or Manager+
   • Assign tags: Admin-only, Manager+, or All users
   • Remove tags: Admin-only, Manager+, or All users
3. Saves permission configuration

Alternative Flows

A1: Restrictive Permissions on Existing Tags

1. If tightening permissions, existing assignments remain
2. New assignments follow new rules

Postconditions

• Tag permission rules are saved
• Enforced on all tag operations

Permission Levels

Summary

AI Chat Integration

The following authentication and admin use cases can be triggered via AI Chat. See AI Chat Specification for full implementation details.

AI Chat-Enabled Actions

Note: Most authentication and admin actions are security-sensitive and are NOT available via AI Chat. These require direct UI interaction for security reasons.

What AI Chat CAN Do for Admin Users

While AI Chat cannot perform most admin actions directly, it can help admin users with:

Information Queries:

• "How many active users do we have?"
• "When was the last user invited?"
• "Show me users who haven't logged in recently"
• "What tags are configured?"

Example Flow:

User: "How many users haven't logged in this month?"

AI: Shows Info Card
┌─────────────────────────────────────────────┐
│ Inactive Users This Month                   │
│                                             │
│ 3 users have not logged in since Dec 1:     │
│                                             │
│ - john.doe@company.com                      │
│   Last login: Nov 15, 2024                  │
│                                             │
│ - jane.smith@company.com                    │
│   Last login: Nov 22, 2024                  │
│                                             │
│ - mike.chen@company.com                     │
│   Last login: Nov 28, 2024                  │
│                                             │
│ [View in User Management]                   │
└─────────────────────────────────────────────┘

Security Restrictions