1193 lines
50 KiB
Markdown
1193 lines
50 KiB
Markdown
# 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
|