# Multi-Tenant UX Flows ## Document Overview This document defines the user experience flows for multi-tenant functionality, SSO integration, and MCP Token management in ColaFlow. It includes user journeys, interaction patterns, and edge case handling. **Version:** 1.0 **Last Updated:** 2025-11-03 **Owner:** UX/UI Team --- ## Table of Contents 1. [Tenant Registration Flow](#tenant-registration-flow) 2. [Login Flows](#login-flows) 3. [SSO Configuration Flow](#sso-configuration-flow) 4. [MCP Token Management Flow](#mcp-token-management-flow) 5. [User Stories](#user-stories) 6. [Edge Cases and Error Handling](#edge-cases-and-error-handling) --- ## Tenant Registration Flow ### User Journey: New Company Signs Up **Goal:** Create a new tenant (company) and first admin account in one seamless flow. ```mermaid flowchart TD A[User visits colaflow.com] --> B[Clicks 'Start Free Trial'] B --> C[Step 1: Company Info] C --> D{Slug Available?} D -->|Yes| E[Step 2: Admin Account] D -->|No| F[Show Error + Suggest Alternatives] F --> C E --> G[Step 3: Choose Plan] G --> H{Submit Registration} H --> I[Create Tenant + Admin User] I --> J[Send Verification Email] J --> K[Redirect to acme.colaflow.com/onboarding] K --> L[Show Welcome Tour] ``` ### Step-by-Step Breakdown #### Step 1: Company Information **URL:** `/signup?step=1` **Fields:** - Company Name (text, required) - Validation: 2-100 characters - Example: "Acme Corporation" - Company Slug (text, required, unique) - Validation: 3-50 characters, lowercase, alphanumeric + hyphens - Real-time availability check (debounced 500ms) - Preview: Shows `acme.colaflow.com` as user types - Suggest alternatives if taken: `acme-corp`, `acme-team`, `acme2` **UI Elements:** - Progress indicator: `● ○ ○` (Step 1 of 3) - "Company Slug" has info tooltip: "This will be your custom ColaFlow URL" - Live preview badge showing the full domain - Green checkmark or red X for availability status **Validation Messages:** - Empty: "Company name is required" - Too short: "Company name must be at least 2 characters" - Slug taken: "This URL is already taken. Try: acme-corp, acme-team" - Invalid characters: "Slug can only contain lowercase letters, numbers, and hyphens" - Reserved: "This name is reserved. Please choose another" **Next Button:** Enabled only when both fields are valid and slug is available. --- #### Step 2: Administrator Account **URL:** `/signup?step=2` **Fields:** - Full Name (text, required) - Validation: 2-100 characters - Email Address (email, required) - Validation: Valid email format - Check: Not already registered - Password (password, required) - Validation: 8+ characters, uppercase, lowercase, number, special char - Real-time strength indicator (Weak / Medium / Strong) - Confirm Password (password, required) - Must match password field **UI Elements:** - Progress indicator: `✓ ● ○` (Step 2 of 3) - Password strength bar (red → yellow → green) - Password requirements checklist: - ☑ At least 8 characters - ☑ One uppercase letter - ☑ One lowercase letter - ☑ One number - ☑ One special character - "Show/Hide password" toggle **Validation Messages:** - Email already exists: "This email is already registered. Try logging in instead?" - Passwords don't match: "Passwords must match" - Weak password: "Password is too weak. Add more complexity" --- #### Step 3: Choose Subscription Plan **URL:** `/signup?step=3` **Plan Options:** | Feature | Free | Starter ($19/mo) | Professional ($49/mo) | Enterprise (Custom) | |---------|------|------------------|----------------------|---------------------| | Users | 5 | 15 | 50 | Unlimited | | Projects | 3 | 20 | 100 | Unlimited | | Storage | 2 GB | 10 GB | 100 GB | 1 TB | | SSO | ✗ | ✗ | ✓ | ✓ | | MCP Tokens | 3 | 10 | 50 | Unlimited | | Support | Community | Email | Priority | Dedicated | **UI Elements:** - Progress indicator: `✓ ✓ ●` (Step 3 of 3) - Plan cards with highlighted "Most Popular" badge on Professional - "Start with Free" / "Start with Starter" buttons - "What's included" expandable sections - Comparison table toggle - Payment method NOT required for Free plan **Interaction:** - Clicking a plan highlights it - "Continue" button shows plan name: "Continue with Free Plan" - For paid plans: Note "14-day free trial, no credit card required" **Final Step:** - Checkbox: "I agree to the Terms of Service and Privacy Policy" - Large "Create Account" button - Processing state: "Creating your workspace..." - Success animation + redirect to `acme.colaflow.com/onboarding` --- ### Success State **Welcome Screen:** ``` ┌──────────────────────────────────────────┐ │ 🎉 Welcome to ColaFlow, Acme Corp! │ │ │ │ Your workspace is ready: │ │ 🌐 acme.colaflow.com │ │ │ │ Next steps: │ │ 1. Invite your team members │ │ 2. Create your first project │ │ 3. Configure integrations │ │ │ │ [Skip Tour] [Start Quick Tour] │ └──────────────────────────────────────────┘ ``` --- ## Login Flows ### Flow 1: Local Login (Email + Password) **URL:** `acme.colaflow.com/login` ```mermaid flowchart TD A[User visits acme.colaflow.com/login] --> B[Tenant Resolved from Subdomain] B --> C{SSO Configured?} C -->|No| D[Show Email + Password Form Only] C -->|Yes| E[Show SSO Buttons + OR + Local Form] D --> F[User Enters Credentials] E --> G{User Chooses Login Method} G -->|Local| F G -->|SSO| H[Redirect to IdP] F --> I[Validate Credentials] I -->|Success| J[Generate JWT] I -->|Failure| K[Show Error: Invalid credentials] J --> L[Redirect to /dashboard] K --> F ``` **Local Login UI:** ``` ┌──────────────────────────────────────────┐ │ Welcome to Acme Corp │ │ │ │ Email Address │ │ [user@acme.com ] │ │ │ │ Password │ │ [******************] [👁] │ │ │ │ [☐] Remember me │ │ Forgot password? │ │ │ │ [Sign In →] │ └──────────────────────────────────────────┘ ``` --- ### Flow 2: SSO Login (Azure AD / Google / Okta) **URL:** `acme.colaflow.com/login` (when SSO is configured) **SSO-Enabled UI:** ``` ┌──────────────────────────────────────────┐ │ Welcome to Acme Corp │ │ │ │ [🟦 Continue with Microsoft] │ │ [🔴 Continue with Google] │ │ │ │ ──────────── OR ──────────── │ │ │ │ Sign in with your email │ │ Email Address │ │ [user@acme.com ] │ │ │ │ Password │ │ [******************] [👁] │ │ │ │ [Sign In →] │ └──────────────────────────────────────────┘ ``` **SSO Flow:** ```mermaid sequenceDiagram participant U as User participant FE as ColaFlow Frontend participant API as ColaFlow API participant IdP as Identity Provider (Azure AD) participant DB as Database U->>FE: Clicks "Continue with Microsoft" FE->>API: POST /api/auth/sso/initiate (provider: AzureAD) API->>DB: Load tenant SSO config DB-->>API: SSO Configuration API->>API: Generate state token (CSRF protection) API-->>FE: Redirect URL + state FE->>IdP: Redirect with OAuth params IdP->>U: Show Microsoft login page U->>IdP: Enter corporate credentials IdP->>API: Callback with authorization code API->>IdP: Exchange code for tokens IdP-->>API: ID Token + Access Token API->>API: Validate ID Token signature API->>DB: Find or create user (auto-provision) DB-->>API: User entity API->>API: Generate JWT with tenant claims API-->>FE: Set JWT in HTTP-only cookie FE->>FE: Store user info in state FE->>U: Redirect to /dashboard ``` **SSO Loading State:** ``` ┌──────────────────────────────────────────┐ │ │ │ Authenticating with │ │ Microsoft... │ │ │ │ [Spinner Animation] │ │ │ │ Please complete sign-in in the popup │ │ │ └──────────────────────────────────────────┘ ``` --- ### Flow 3: SSO Callback **URL:** `/auth/sso/callback?code=xxx&state=yyy` **States:** 1. **Loading:** Show spinner with "Completing sign-in..." 2. **Success:** Brief success message + redirect to dashboard 3. **Error:** Show error with "Back to Login" button **Error Messages:** - "Authentication failed: Invalid state parameter" (CSRF) - "Authentication failed: Email domain not allowed" - "Authentication failed: User account suspended" - "Authentication failed: SSO session expired" --- ## SSO Configuration Flow ### User Journey: Admin Configures SSO **Role:** Tenant Administrator **Goal:** Enable SSO for company users ```mermaid flowchart TD A[Admin navigates to Settings] --> B[Click 'Single Sign-On'] B --> C[See empty state / current config] C --> D[Click 'Configure SSO'] D --> E[Select SSO Provider] E --> F{Provider Type} F -->|OIDC| G[Enter Authority, Client ID, Secret] F -->|SAML| H[Enter Entity ID, SSO URL, Certificate] G --> I[Configure Auto-Provisioning] H --> I I --> J[Add Allowed Email Domains] J --> K[Click 'Test Connection'] K --> L{Test Result} L -->|Success| M[Show Success Message] L -->|Failure| N[Show Error Details] N --> G M --> O[Click 'Save Configuration'] O --> P[SSO Enabled Successfully] P --> Q[Show confirmation + instructions] ``` ### Empty State **URL:** `/settings/sso` ``` ┌────────────────────────────────────────────────┐ │ Single Sign-On (SSO) │ ├────────────────────────────────────────────────┤ │ │ │ 🔐 │ │ │ │ Enable enterprise SSO for your team │ │ │ │ SSO allows your team to log in with their │ │ corporate credentials (Azure AD, Google, │ │ Okta, or SAML 2.0). │ │ │ │ ✓ Centralized access control │ │ ✓ No need to remember passwords │ │ ✓ Automatic user provisioning │ │ │ │ [Configure SSO] │ │ │ │ ℹ️ Available for Professional and Enterprise │ │ plans only │ └────────────────────────────────────────────────┘ ``` --- ### SSO Configuration Form **Tabs:** General | OIDC Config | SAML Config | Users | Test #### Tab 1: General ``` Provider * [Azure AD ▼] - Azure AD / Microsoft Entra - Google Workspace - Okta - Generic SAML 2.0 Auto-Provision Users [✓] Automatically create accounts for new users Require Email Verification [☐] Require users to verify email after SSO login Allowed Email Domains (Optional) [@acme.com ] [+ Add] [@acme.co.uk ] [🗑️] Restriction: Only users with these email domains can log in via SSO. Leave empty to allow all domains. ``` #### Tab 2: OIDC Config (for Azure AD, Google, Okta) ``` Authority / Issuer URL * [https://login.microsoftonline.com/tenant-id] ℹ️ For Azure AD: Get this from Azure Portal → App Registrations Client ID * [xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx] ℹ️ Your application's Client ID from the IdP Client Secret * [********************] [Show] ℹ️ Keep this secret secure. It will be encrypted in our database. Metadata URL (Optional) [https://login.microsoftonline.com/.well-known/openid-configuration] ℹ️ Auto-discovery endpoint for OIDC metadata Callback URL (Read-only) [https://acme.colaflow.com/api/auth/sso/callback] ℹ️ Configure this URL in your IdP's allowed redirect URIs [Copy] ``` **Provider-Specific Help:** - **Azure AD:** Link to "How to register an app in Azure AD" - **Google:** Link to "Google Cloud Console setup guide" - **Okta:** Link to "Okta application setup guide" #### Tab 3: SAML Config (for Generic SAML) ``` Entity ID * [https://idp.acme.com/saml] ℹ️ Your IdP's entity identifier Single Sign-On URL * [https://idp.acme.com/sso] ℹ️ The IdP endpoint where SAML authentication requests are sent X.509 Certificate * [-----BEGIN CERTIFICATE----- MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcN... -----END CERTIFICATE----- ] ℹ️ IdP's public certificate for signature verification. Paste the full certificate including BEGIN/END lines. Metadata URL (Optional) [https://idp.acme.com/metadata.xml] ℹ️ If provided, we'll automatically fetch IdP metadata Service Provider Metadata (Read-only) [https://acme.colaflow.com/api/auth/sso/saml/metadata] ℹ️ Provide this URL to your IdP for automatic configuration [Copy] [Download XML] ``` #### Tab 4: Users Show list of users who have logged in via SSO: ``` SSO Users (12) [Search users...] ┌─────────────────────────────────────────────────────────┐ │ Name Email Last Login Status │ ├─────────────────────────────────────────────────────────┤ │ John Doe john@acme.com 2 hours ago Active │ │ Jane Smith jane@acme.com 1 day ago Active │ │ Bob Johnson bob@acme.com Never Pending│ └─────────────────────────────────────────────────────────┘ Auto-provisioned: 10 Manually created: 2 ``` #### Tab 5: Test Connection ``` Test SSO Configuration Before enabling SSO for your team, verify that your configuration is correct. [Test Connection] Test Results: ┌─────────────────────────────────────────────────────────┐ │ ✓ Metadata endpoint reachable │ │ ✓ OIDC discovery document valid │ │ ✓ Certificate signature valid │ │ ✓ Callback URL whitelisted │ │ │ │ Status: All checks passed ✓ │ └─────────────────────────────────────────────────────────┘ [< Back] [Save Configuration] ``` **Test Failure Example:** ``` Test Results: ┌─────────────────────────────────────────────────────────┐ │ ✓ Metadata endpoint reachable │ │ ✗ Failed to validate client secret │ │ Error: Invalid client credentials │ │ │ │ Status: Configuration has errors ✗ │ │ │ │ Troubleshooting: │ │ 1. Verify your Client ID and Secret in Azure Portal │ │ 2. Ensure the application has correct permissions │ │ 3. Check that the callback URL is whitelisted │ └─────────────────────────────────────────────────────────┘ [< Back to Configuration] ``` --- ### Success State After saving SSO configuration: ``` ┌────────────────────────────────────────────────┐ │ ✓ SSO Configuration Saved │ ├────────────────────────────────────────────────┤ │ │ │ Azure AD SSO is now enabled for Acme Corp. │ │ │ │ Your team can now log in using their │ │ @acme.com Microsoft accounts. │ │ │ │ Next steps: │ │ 1. Test SSO login with your account │ │ 2. Share login URL with your team: │ │ https://acme.colaflow.com/login │ │ 3. Disable local passwords (optional) │ │ │ │ [Test SSO Login] [Invite Team] │ └────────────────────────────────────────────────┘ ``` --- ## MCP Token Management Flow ### User Journey: Generate MCP Token for AI Agent **Role:** Any authorized user **Goal:** Create an MCP token for Claude Desktop / ChatGPT integration ```mermaid flowchart TD A[User navigates to Settings → MCP Tokens] --> B{Has Tokens?} B -->|No| C[Show Empty State] B -->|Yes| D[Show Token List] C --> E[Click 'Generate Token'] D --> E E --> F[Step 1: Token Info] F --> G[Step 2: Configure Permissions] G --> H[Step 3: Review & Create] H --> I[Token Generated] I --> J[Display Token ONE TIME ONLY] J --> K{User Action} K -->|Copy| L[Token Copied to Clipboard] K -->|Download| M[Download .env File] L --> N[User Confirms 'I've saved it'] M --> N N --> O[Token Hidden Forever] O --> P[Show in Token List] ``` ### Empty State **URL:** `/settings/mcp-tokens` ``` ┌────────────────────────────────────────────────┐ │ MCP API Tokens │ ├────────────────────────────────────────────────┤ │ │ │ 🤖 │ │ │ │ Connect AI agents to ColaFlow │ │ │ │ MCP Tokens allow AI assistants like Claude │ │ and ChatGPT to access your projects, create │ │ tasks, and generate reports on your behalf. │ │ │ │ ✓ Fine-grained permissions │ │ ✓ Revocable at any time │ │ ✓ Full audit trail │ │ │ │ [Generate Your First Token] │ │ │ │ 📖 Learn more about MCP integration │ └────────────────────────────────────────────────┘ ``` --- ### Token List View ``` ┌────────────────────────────────────────────────────────────────┐ │ MCP API Tokens │ │ │ │ [+ Generate New Token] [Filter: All ▼] │ ├────────────────────────────────────────────────────────────────┤ │ │ │ Active Tokens (3) │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Claude Desktop │ │ │ │ Permissions: Projects (R), Issues (R/W), Documents (R) │ │ │ │ Created: 2025-11-01 • Last Used: 2 hours ago │ │ │ │ Expires: In 30 days │ │ │ │ │ │ │ │ [View Details] [Revoke] │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ ChatGPT Assistant │ │ │ │ Permissions: Projects (R), Issues (R), Reports (R) │ │ │ │ Created: 2025-10-20 • Last Used: Yesterday │ │ │ │ Expires: In 60 days │ │ │ │ │ │ │ │ [View Details] [Revoke] │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ CI/CD Pipeline │ │ │ │ Permissions: Issues (C/U), Sprints (R) │ │ │ │ Created: 2025-10-15 • Last Used: Never │ │ │ │ Expires: Never │ │ │ │ │ │ │ │ [View Details] [Revoke] │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ Revoked Tokens (1) [Show] │ └────────────────────────────────────────────────────────────────┘ ``` --- ### Token Generation Modal #### Step 1: Token Information ``` ┌────────────────────────────────────────────────┐ │ Generate New MCP Token [× ] │ ├────────────────────────────────────────────────┤ │ Step 1 of 3: Token Information ● ○ ○ │ │ │ │ Token Name * │ │ [Claude Desktop ] │ │ ℹ️ A friendly name to identify this token │ │ │ │ Description (Optional) │ │ [Used for my personal AI assistant ] │ │ [that helps manage my tasks ] │ │ │ │ Expiration │ │ [◉] 30 days │ │ [○] 60 days │ │ [○] 90 days │ │ [○] Never (Enterprise only) │ │ │ │ ℹ️ You can revoke this token at any time │ │ │ │ [Cancel] [Next →] │ └────────────────────────────────────────────────┘ ``` #### Step 2: Configure Permissions **Option A: Template-Based** ``` ┌────────────────────────────────────────────────┐ │ Generate New MCP Token [× ] │ ├────────────────────────────────────────────────┤ │ Step 2 of 3: Permissions ○ ● ○ │ │ │ │ Choose a Permission Template │ │ │ │ [◉] Read Only (Recommended) │ │ View projects, issues, and documents. │ │ Cannot make changes. │ │ │ │ [○] Read + Write │ │ View and create issues/documents. │ │ Cannot delete. │ │ │ │ [○] Custom │ │ Define specific permissions below. │ │ │ │ ────────────────────────────────────────── │ │ │ │ Advanced Options (Optional) │ │ │ │ Require Approval For: │ │ [☐] Issue status changes │ │ [☐] Document publishing │ │ [☐] Project archiving │ │ │ │ ℹ️ AI will submit changes for human review │ │ │ │ [← Back] [Next →] │ └────────────────────────────────────────────────┘ ``` **Option B: Permission Matrix (if Custom selected)** ``` ┌─────────────────────────────────────────────────────┐ │ Generate New MCP Token [× ] │ ├─────────────────────────────────────────────────────┤ │ Step 2 of 3: Custom Permissions ○ ● ○ │ │ │ │ Select permissions for each resource type: │ │ │ │ Resource │ Read │Create│Update│Delete│Search │ │ ───────────┼──────┼──────┼──────┼──────┼──────── │ │ Projects │ ✓ │ │ │ │ ✓ │ │ Issues │ ✓ │ ✓ │ ✓ │ │ ✓ │ │ Documents │ ✓ │ ✓ │ │ │ ✓ │ │ Reports │ ✓ │ │ │ │ │ │ Sprints │ ✓ │ │ │ │ ✓ │ │ Comments │ ✓ │ ✓ │ │ │ │ │ │ │ ⚠️ Delete permissions are restricted for safety │ │ │ │ Selected: 13 permissions │ │ │ │ [← Back] [Next →] │ └─────────────────────────────────────────────────────┘ ``` #### Step 3: Review & Create ``` ┌────────────────────────────────────────────────┐ │ Generate New MCP Token [× ] │ ├────────────────────────────────────────────────┤ │ Step 3 of 3: Review ○ ○ ● │ │ │ │ Review Your Token Configuration │ │ │ │ Name: Claude Desktop │ │ Description: Used for my personal AI... │ │ Expires: In 30 days (2025-12-03) │ │ │ │ Permissions: │ │ Projects: Read, Search │ │ Issues: Read, Create, Update, Search │ │ Documents: Read, Create, Search │ │ Reports: Read │ │ │ │ Restrictions: │ │ Issue status changes require approval │ │ │ │ ℹ️ You'll see the token only once after │ │ creation. Make sure to copy and save it. │ │ │ │ [← Back] [Create Token] │ └────────────────────────────────────────────────┘ ``` --- ### Token Display (One-Time Only) ``` ┌─────────────────────────────────────────────────────┐ │ ✓ Token Created Successfully! [× ] │ ├─────────────────────────────────────────────────────┤ │ │ │ ⚠️ IMPORTANT: Save this token now! │ │ │ │ This is the ONLY time you'll see this token. │ │ If you lose it, you'll need to generate a new one. │ │ │ │ Your Token: │ │ ┌─────────────────────────────────────────────┐ │ │ │ mcp_acme_7f3d8a9c4e1b2f5a6d8c9e0f1a2b3c4d │ │ │ └─────────────────────────────────────────────┘ │ │ [📋 Copy to Clipboard] │ │ │ │ ────────────────────────────────────────────── │ │ │ │ How to Use This Token: │ │ │ │ 1. Copy the token above │ │ 2. Add it to your AI assistant's configuration: │ │ - Claude Desktop: Settings → MCP Servers │ │ - ChatGPT: Custom GPT configuration │ │ 3. Set as environment variable: │ │ COLAFLOW_MCP_TOKEN=mcp_acme_xxx... │ │ │ │ [Download as .env file] │ │ │ │ ────────────────────────────────────────────── │ │ │ │ [☐] I have saved this token securely │ │ │ │ [Close] │ └─────────────────────────────────────────────────────┘ ``` **Interaction:** - "Copy to Clipboard" button shows success toast: "Token copied!" - "Download as .env file" downloads a file named `colaflow-mcp-token.env`: ``` # ColaFlow MCP Token # Token Name: Claude Desktop # Created: 2025-11-03 # Expires: 2025-12-03 COLAFLOW_MCP_TOKEN=mcp_acme_7f3d8a9c4e1b2f5a6d8c9e0f1a2b3c4d ``` - Checkbox must be checked to enable "Close" button - Closing without checking shows confirmation: "Are you sure? You won't be able to see this token again." --- ### Token Details Page **URL:** `/settings/mcp-tokens/[tokenId]` ``` ┌─────────────────────────────────────────────────────┐ │ [← Back to Tokens] │ │ │ │ Claude Desktop [Active] │ │ Created on November 1, 2025 │ ├─────────────────────────────────────────────────────┤ │ │ │ 📋 Token Information │ │ │ │ Name: Claude Desktop │ │ Description: Used for my personal AI assistant │ │ Created: 2025-11-01 10:30 AM │ │ Last Used: 2 hours ago (2025-11-03 08:15 AM) │ │ Expires: In 27 days (2025-12-01) │ │ Status: Active │ │ Usage Count: 1,247 requests │ │ │ │ 🔐 Permissions │ │ │ │ Projects │ │ ✓ Read ✗ Create ✗ Update ✗ Delete │ │ │ │ Issues │ │ ✓ Read ✓ Create ✓ Update ✗ Delete │ │ │ │ Documents │ │ ✓ Read ✓ Create ✗ Update ✗ Delete │ │ │ │ Reports │ │ ✓ Read ✗ Create ✗ Update ✗ Delete │ │ │ │ 📊 Recent Activity (Last 7 Days) │ │ │ │ Chart: [Activity line graph showing API calls] │ │ │ │ 📝 Audit Log │ │ [Showing last 50 operations] │ │ │ │ Timestamp Action Resource Result │ │ ───────────────── ────────── ───────── ─────── │ │ 2025-11-03 08:15 Read Issue #123 Success │ │ 2025-11-03 08:10 Create Issue #456 Success │ │ 2025-11-03 08:05 Update Issue #456 Success │ │ 2025-11-03 08:00 Read Project #1 Success │ │ 2025-11-03 07:55 Search Issues Success │ │ ... │ │ │ │ [Load More] │ │ │ │ ⚠️ Danger Zone │ │ │ │ [Revoke This Token] │ │ Once revoked, this token will stop working │ │ immediately. This action cannot be undone. │ │ │ └─────────────────────────────────────────────────────┘ ``` **Revoke Confirmation:** ``` ┌────────────────────────────────────────────────┐ │ Revoke Token? │ ├────────────────────────────────────────────────┤ │ │ │ Are you sure you want to revoke this token? │ │ │ │ Token: Claude Desktop │ │ Last used: 2 hours ago │ │ │ │ This will: │ │ • Immediately stop all API access │ │ • Cannot be undone │ │ • You'll need to generate a new token │ │ │ │ Reason for Revocation (Optional) │ │ [No longer needed ] │ │ │ │ [Cancel] [Revoke Token] │ └────────────────────────────────────────────────┘ ``` --- ## User Stories ### Story 1: First-Time Company Registration **As a** startup founder **I want to** quickly sign up for ColaFlow with my company **So that** I can start managing my projects immediately **Acceptance Criteria:** - Can complete registration in under 2 minutes - Company slug is validated in real-time - Password requirements are clear - Can choose a plan without entering payment info - Receive a welcome email with next steps --- ### Story 2: SSO Login for Enterprise User **As an** enterprise employee **I want to** log in with my corporate Microsoft account **So that** I don't need to remember another password **Acceptance Criteria:** - SSO button is prominently displayed on login page - Login flow completes in under 10 seconds - My profile info (name, email, avatar) is auto-populated - I'm automatically added to my company's workspace - I can still use local login if SSO fails --- ### Story 3: Admin Configures SSO **As a** company administrator **I want to** configure Azure AD SSO for my team **So that** everyone can log in with their corporate accounts **Acceptance Criteria:** - Step-by-step wizard with clear instructions - Can test connection before saving - Provider-specific help documentation available - Can restrict SSO to specific email domains - Can auto-provision users on first login --- ### Story 4: Developer Creates MCP Token for Claude **As a** developer **I want to** create an MCP token for my Claude Desktop app **So that** Claude can help me manage tasks automatically **Acceptance Criteria:** - Can generate token in under 1 minute - Permission templates make setup easy - Token is displayed only once with clear warning - Can copy token or download .env file - Instructions for Claude Desktop setup included --- ### Story 5: User Reviews Token Activity **As a** security-conscious user **I want to** see all API activity for my MCP tokens **So that** I can verify there's no unauthorized access **Acceptance Criteria:** - Can view detailed audit log for each token - Can see usage charts and statistics - Can quickly identify unusual activity - Can revoke token immediately if needed - Revocation takes effect instantly --- ## Edge Cases and Error Handling ### Registration Edge Cases 1. **Slug Already Taken** - **Detection:** Real-time check on blur/debounced typing - **Message:** "This URL is already taken. Try: acme-corp, acme-team, acme2" - **Action:** Suggest 3 alternatives - **Recovery:** User can edit slug field 2. **Email Already Registered** - **Detection:** On submit (Step 2) - **Message:** "This email is already registered. Try logging in instead? [Log In]" - **Action:** Offer direct link to login page - **Recovery:** User can use different email 3. **Network Failure During Registration** - **Detection:** Timeout or connection error - **Message:** "Connection lost. Your progress is saved. [Retry]" - **Action:** Save form state in session storage - **Recovery:** Restore form on retry 4. **Reserved Slug** - **Detection:** Real-time validation - **Message:** "This name is reserved. Please choose another." - **List:** www, api, admin, app, dashboard, docs, blog, support - **Recovery:** User must choose different slug --- ### Login Edge Cases 1. **Wrong Password (3+ Attempts)** - **Detection:** Track failed attempts per user - **Message:** "Too many failed attempts. Your account is temporarily locked for 15 minutes." - **Action:** Throttle login attempts - **Recovery:** Wait or use "Forgot Password" 2. **Suspended Account** - **Detection:** Check user.status on login - **Message:** "Your account has been suspended. Contact support for assistance." - **Action:** Block login - **Recovery:** Support ticket 3. **SSO Misconfiguration** - **Detection:** SSO flow fails - **Message:** "SSO login is currently unavailable. Use your email and password instead." - **Action:** Fall back to local login - **Recovery:** Admin fixes SSO config 4. **Email Domain Not Allowed (SSO)** - **Detection:** After IdP callback - **Message:** "Your email domain (@external.com) is not allowed for SSO. Contact your administrator." - **Action:** Reject login - **Recovery:** Admin adds domain to allowed list 5. **Expired SSO Session** - **Detection:** IdP returns error - **Message:** "Your SSO session has expired. Please log in again." - **Action:** Redirect to login - **Recovery:** User retries login --- ### SSO Configuration Edge Cases 1. **Invalid Client Secret** - **Detection:** Test connection fails - **Message:** "Failed to authenticate with IdP: Invalid client credentials" - **Troubleshooting:** - Verify Client ID and Secret in IdP portal - Check application permissions - Ensure redirect URIs are correct - **Recovery:** User corrects credentials 2. **Certificate Parse Error (SAML)** - **Detection:** Certificate validation fails - **Message:** "Invalid X.509 certificate format. Ensure you've copied the full certificate including BEGIN/END markers." - **Action:** Show certificate format example - **Recovery:** User pastes correct certificate 3. **Callback URL Not Whitelisted** - **Detection:** IdP returns redirect_uri_mismatch - **Message:** "Callback URL not whitelisted in IdP. Add https://acme.colaflow.com/api/auth/sso/callback to allowed redirect URIs." - **Action:** Show copy button for callback URL - **Recovery:** User updates IdP config 4. **SSO Enabled But No Users Can Log In** - **Detection:** Email domain restrictions too strict - **Message:** "Warning: No users match your allowed domains. Add @acme.com to allow your team." - **Action:** Suggest adding domains - **Recovery:** Admin adds domains --- ### MCP Token Edge Cases 1. **Token Generation Fails** - **Detection:** Server error on create - **Message:** "Failed to generate token. Please try again. If the problem persists, contact support." - **Action:** Log error - **Recovery:** User retries 2. **User Closes Modal Without Saving Token** - **Detection:** User clicks [X] or clicks outside - **Message:** "Are you sure? You won't be able to see this token again." - **Action:** Show confirmation dialog - **Recovery:** User can go back or confirm closure 3. **User Tries to View Token Again** - **Detection:** User clicks on token in list - **Message:** "For security, tokens cannot be viewed after creation. Generate a new token if needed." - **Action:** Show token details but not the actual token - **Recovery:** User generates new token 4. **Token Expired But Still in Use** - **Detection:** API call with expired token - **Message:** (To AI agent) "Token expired. Please regenerate." - **Action:** Return 401 Unauthorized - **Recovery:** User generates new token 5. **Revoke Token That's Actively Being Used** - **Detection:** Usage detected in last 5 minutes - **Message:** "This token was used 3 minutes ago. Revoking will immediately stop all access. Continue?" - **Action:** Show extra confirmation - **Recovery:** User confirms or cancels 6. **Zero Permissions Selected** - **Detection:** Form validation on Step 2 - **Message:** "You must select at least one permission for this token." - **Action:** Highlight permissions section - **Recovery:** User selects permissions 7. **Attempt to Delete Resource (Forbidden)** - **Detection:** API permission check - **Message:** (To AI agent) "Permission denied: Token does not have delete permission for issues." - **Action:** Log attempt in audit log - **Recovery:** User grants delete permission if needed --- ### Network and Performance Edge Cases 1. **Slow API Response (>3s)** - **UI:** Show loading skeleton - **Message:** "Loading..." - **Timeout:** 30s, then show error - **Recovery:** Retry button 2. **Offline Mode** - **Detection:** navigator.onLine = false - **Message:** "You're offline. Some features may not work." - **Action:** Show banner at top - **Recovery:** Auto-hide when online 3. **Session Expired** - **Detection:** 401 from API - **Message:** "Your session has expired. Please log in again." - **Action:** Redirect to login with return URL - **Recovery:** User logs in again --- ## Animation and Timing Guidelines ### Micro-interactions - **Button Hover:** 150ms ease-out - **Input Focus:** 200ms ease-in-out - **Tooltip Appear:** 300ms ease-out with 500ms delay - **Toast Notification:** 300ms slide-in, auto-dismiss after 4s ### Page Transitions - **Route Change:** 300ms fade-in - **Modal Open:** 300ms scale-in + fade-in - **Modal Close:** 200ms scale-out + fade-out - **Drawer Open:** 300ms slide-in - **Accordion Expand:** 300ms ease-out ### Loading States - **Button Loading:** Show spinner immediately, min 500ms - **Page Loading:** Show skeleton after 200ms - **API Call:** Show spinner after 500ms (hide for fast responses) --- ## Conclusion This UX flow document provides comprehensive guidance for implementing multi-tenant, SSO, and MCP token management features. All flows prioritize security, clarity, and user control while maintaining a seamless experience. **Next Steps:** 1. Review with product team 2. Create UI mockups based on these flows 3. Implement frontend components 4. Conduct usability testing **Questions or Feedback:** Contact UX/UI team at ux@colaflow.com