@cdmbase/wiki-browser 12.0.18-alpha.10

package/lib/templates/content/docs/adminide-modules/project-tools/tenant-management/tenant-management.md

@@ -0,0 +1,708 @@
+# Tenant Management System - Complete Setup & Usage Guide
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Prerequisites](#prerequisites)
+3. [Creating a Tenant](#creating-a-tenant)
+4. [Understanding API Keys (Client Configurations)](#understanding-api-keys-client-configurations)
+5. [Authentication & Usage](#authentication--usage)
+6. [Managing Tenants](#managing-tenants)
+7. [API Integration Examples](#api-integration-examples)
+8. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+The Tenant Management System provides **multi-tenancy support** for your application, allowing you to:
+
+- Isolate resources per tenant
+- Authenticate API requests using tenant-specific credentials
+- Manage multiple API keys per tenant
+- Track tenant status and configurations
+- Associate tenants with organizations and projects
+
+### Key Concepts
+
+- **Tenant**: An isolated instance representing a client/customer in your system
+- **Client Configurations (API Keys)**: Keycloak-based authentication credentials for accessing tenant resources
+- **Project/Vault**: A logical grouping that tenants belong to (for resource management)
+- **Environment Tag**: Deployment environment (development, staging, production)
+- **Organization**: The owning organization of the tenant
+
+---
+
+## Prerequisites
+
+Before creating a tenant, ensure you have the following set up:
+
+### 1. **Organization**
+
+Your tenant must belong to an organization.
+
+```typescript
+// Organizations are managed separately in the system
+// Ensure you have an organization ID or slug available
+const organizationSlug = 'my-company';
+```
+
+### 2. **Project (Vault)**
+
+Projects provide logical grouping and resource isolation.
+
+**Creating a Project:**
+
+- Navigate to **Project Management** in your dashboard
+- Click **"Create Project"**
+- Provide:
+    - Project Name (e.g., "Production Services")
+    - Description
+    - Associated Organization
+
+**Note:** The `vault` field in tenant creation maps to `project`. This is used for:
+
+- Resource scoping
+- Access control
+- Billing/usage tracking
+
+### 3. **Environment Tag**
+
+Environment tags categorize deployments.
+
+**Available Environments:**
+
+- `development` - For dev/test environments
+- `staging` - Pre-production testing
+- `production` - Live production environment
+
+**Creating Environment Tags:**
+
+```graphql
+# Environment tags are typically created during system setup
+# Contact your system administrator if tags are missing
+```
+
+### 4. **Keycloak Configuration**
+
+Ensure your Keycloak instance is configured:
+
+- Keycloak server URL: `KEYCLOAK_SERVER_DOMAIN`
+- Realm name: `KEYCLOAK_REALM`
+- Admin credentials configured
+
+---
+
+## Creating a Tenant
+
+### Via UI (Recommended)
+
+1. **Navigate to Tenant Management**
+    - Go to `/{organizationSlug}/tenants`
+    - Click **"Create Tenant"** button
+
+2. **Fill in Tenant Details**
+
+    | Field       | Required    | Description                                    |
+    | ----------- | ----------- | ---------------------------------------------- |
+    | Name        | ✅ Yes      | Tenant display name (e.g., "Acme Corp API")    |
+    | Description | ✅ Yes      | Purpose or details about the tenant            |
+    | Environment | ✅ Yes      | Select development/staging/production          |
+    | Project     | ⚠️ Optional | Associate with a project for resource tracking |
+    | Auth Type   | ✅ Yes      | Authentication method (default: ClientSecret)  |
+
+3. **Add API Keys (Client Configurations)**
+
+    **⚠️ Important:** You must add at least one API key during creation.
+
+    Click **"Add Secret Key"** and provide:
+    - **Name**: Unique identifier (e.g., "PRODUCTION_API_KEY", "MOBILE_APP_KEY")
+    - **Description**: Optional note about key usage
+
+    You can add multiple keys for different applications/services.
+
+4. **Submit**
+    - Click **"Create Tenant"**
+    - Status will initially be **"PENDING"**
+    - Keycloak clients are created asynchronously via Inngest workflow
+    - Status changes to **"ACTIVE"** once complete
+
+### Via GraphQL API
+
+```graphql
+mutation CreateTenant($input: TenantInput!) {
+    createTenant(input: $input) {
+        tenant {
+            id
+            tenantId
+            name
+            status
+            clientConfigurations {
+                id
+                name
+                clientId
+            }
+        }
+        jobId
+        message
+    }
+}
+```
+
+**Variables:**
+
+```json
+{
+    "input": {
+        "name": "Acme Corp Production",
+        "description": "Production API tenant for Acme Corp",
+        "organization": "my-company",
+        "vault": "64f3a1b2c9d8e7f6a5b4c3d2",
+        "environmentTag": "64a2b3c4d5e6f7g8h9i0j1k2",
+        "authType": "ClientSecret",
+        "clientConfigurations": [
+            {
+                "name": "WEB_APP_KEY",
+                "description": "API key for web application"
+            },
+            {
+                "name": "MOBILE_APP_KEY",
+                "description": "API key for mobile apps"
+            }
+        ]
+    }
+}
+```
+
+### What Happens During Creation?
+
+1. **Tenant Record Created**
+    - Stored in MongoDB with status `PENDING`
+    - Generates unique `tenantId` (UUID)
+    - Creates `appName` (slug version of name)
+    - Generates `connectionId` for internal tracking
+
+2. **Keycloak Client Creation (Async)**
+    - Inngest workflow triggered: `TENANT_MGMT_CREATE_CLIENT_EVENT`
+    - For each `clientConfiguration`:
+        - Creates Keycloak confidential client
+        - Generates client credentials
+        - Stores `clientId` in tenant record
+
+3. **Status Update**
+    - Changes to `ACTIVE` on success
+    - Changes to `ERROR` if creation fails (can be retried)
+
+---
+
+## Understanding API Keys (Client Configurations)
+
+### What are Client Configurations?
+
+Client Configurations are **Keycloak-based API keys** that authenticate requests to your tenant.
+
+### Key Components
+
+Each API key consists of:
+
+| Component         | Description                | Example                        |
+| ----------------- | -------------------------- | ------------------------------ |
+| **Name**          | Human-readable identifier  | `PRODUCTION_API_KEY`           |
+| **Client ID**     | Keycloak client identifier | `64f3a1b2-c9d8-e7f6-a5b4-c3d2` |
+| **Client Secret** | Authentication password    | `dGVzdHNlY3JldGZvcmF1dGg=`     |
+| **Created At**    | Timestamp                  | `2025-11-11T08:00:00Z`         |
+
+### Secret Generation
+
+Secrets are **deterministically generated** using:
+
+```typescript
+generateSecretFromName(keyName, tenantId);
+```
+
+Formula:
+
+```
+secret = SHA256(keyName + tenantId + SALT)
+  .toBase64()
+  .removeNonAlphanumeric()
+  .substring(0, 32)
+```
+
+This ensures:
+
+- ✅ Reproducible (can be regenerated)
+- ✅ Unique per tenant
+- ✅ Keycloak-compatible (32 chars, alphanumeric)
+
+### Viewing API Keys
+
+**In UI:**
+
+1. Go to Tenant Management
+2. Click **"Actions" → "View Details"** on a tenant
+3. Scroll to **"Secret API Keys"** section
+4. Click **"Reveal"** to view the full secret
+5. Click **"Copy"** to copy to clipboard
+
+**Via GraphQL:**
+
+```graphql
+mutation RevealSecretKey($tenantId: ID!, $keyId: ID!) {
+    revealSecretKey(tenantId: $tenantId, keyId: $keyId)
+}
+```
+
+**Response:**
+
+```
+"base64EncodedClientId:Secret"
+```
+
+### Managing API Keys
+
+**Add New Key** (During Update):
+
+```graphql
+mutation UpdateTenant($id: ID!, $input: TenantUpdateInput!) {
+    updateTenant(id: $id, input: $input) {
+        id
+        clientConfigurations {
+            id
+            name
+            clientId
+        }
+    }
+}
+```
+
+**Revoke Key:**
+
+```graphql
+mutation RevokeSecretKey($tenantId: ID!, $keyId: ID!) {
+    revokeSecretKey(tenantId: $tenantId, keyId: $keyId)
+}
+```
+
+---
+
+## Authentication & Usage
+
+### How Tenant Authentication Works
+
+The system uses **header-based authentication** validated against Keycloak.
+
+#### Authentication Flow
+
+```
+┌─────────────┐
+│   Client    │
+│ Application │
+└──────┬──────┘
+       │ 1. Make API Request
+       │    Headers:
+       │    - x-tenant-id: {tenantId}
+       │    - x-tenant-key: {base64(clientId:secret)}
+       │
+       ▼
+┌──────────────────────────────────────┐
+│  Middleware: cached-tenant-info      │
+│                                      │
+│  2. Extract Headers                  │
+│  3. Lookup Tenant in MongoDB         │
+│  4. Validate with Keycloak           │
+│     - Verify clientId exists         │
+│     - Check credentials valid        │
+└──────┬───────────────────────────────┘
+       │
+       ▼
+┌─────────────────┐
+│  Request Valid  │◄─── Success (200)
+│  Set req.tenant │
+└─────────────────┘
+
+       │
+       ▼
+┌─────────────────┐
+│ Unauthorized    │◄─── Failure (401)
+│ Error Response  │
+└─────────────────┘
+```
+
+### Implementation (Middleware)
+
+Located in: `cached-tenant-info.middleware.ts`
+
+**Key Functions:**
+
+1. **Header Extraction**
+
+```typescript
+const tenantId = req.headers['x-tenant-id'];
+const tenantKey = req.headers['x-tenant-key'];
+```
+
+2. **Tenant Lookup**
+
+```typescript
+const tenantData = await TenantModel.findById(tenantId);
+```
+
+3. **Keycloak Validation**
+
+```typescript
+// Decode: clientId:secret
+const [clientId, clientSecret] = Buffer.from(tenantKey, 'base64').toString('utf-8').split(':');
+
+// Verify against Keycloak
+const isValid = await keycloakAdminService.verifyClientCredentials(clientId, clientSecret);
+```
+
+4. **Authorization**
+
+```typescript
+if (isValid) {
+    req.tenant = tenantData; // Attach tenant to request
+    next();
+} else {
+    res.status(401).json({ error: 'Invalid tenant credentials' });
+}
+```
+
+---
+
+## API Integration Examples
+
+### Node.js / JavaScript
+
+```javascript
+const axios = require('axios');
+
+// Your tenant credentials
+const TENANT_ID = '64f3a1b2c9d8e7f6a5b4c3d2';
+const CLIENT_ID = 'your-keycloak-client-id';
+const CLIENT_SECRET = 'your-client-secret';
+
+// Encode credentials
+const tenantKey = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');
+
+// Make authenticated request
+axios
+    .post(
+        'https://api.yourapp.com/graphql',
+        {
+            query: `
+    query GetData {
+      myData {
+        id
+        name
+      }
+    }
+  `,
+        },
+        {
+            headers: {
+                'x-tenant-id': TENANT_ID,
+                'x-tenant-key': tenantKey,
+                'Content-Type': 'application/json',
+            },
+        },
+    )
+    .then((response) => console.log(response.data))
+    .catch((error) => console.error(error));
+```
+
+### cURL
+
+```bash
+# Your credentials
+TENANT_ID="64f3a1b2c9d8e7f6a5b4c3d2"
+CLIENT_ID="your-keycloak-client-id"
+CLIENT_SECRET="your-client-secret"
+
+# Encode credentials
+TENANT_KEY=$(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)
+
+# Make request
+curl -X POST https://api.yourapp.com/graphql \
+  -H "x-tenant-id: ${TENANT_ID}" \
+  -H "x-tenant-key: ${TENANT_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "query GetData { myData { id name } }"
+  }'
+```
+
+---
+
+## Managing Tenants
+
+### Viewing Tenants
+
+**UI:**
+
+- Navigate to `/{organizationSlug}/tenants`
+- View list of all tenants with:
+    - Name, Description
+    - Environment
+    - Status (Pending, Active, Error)
+    - Created date
+
+**GraphQL:**
+
+```graphql
+query GetTenants($orgName: String!) {
+    tenants(orgName: $orgName) {
+        id
+        tenantId
+        name
+        description
+        status
+        environmentTag {
+            name
+        }
+        clientConfigurations {
+            id
+            name
+            createdAt
+        }
+    }
+}
+```
+
+### Updating Tenants
+
+**UI:**
+
+1. Click **"Actions" → "Edit"** on a tenant
+2. Modify:
+    - Name
+    - Description
+    - Environment Tag
+    - Project
+3. **Add new API keys** if needed
+4. Click **"Update Tenant"**
+
+**GraphQL:**
+
+```graphql
+mutation UpdateTenant($id: ID!, $input: TenantUpdateInput!) {
+    updateTenant(id: $id, input: $input) {
+        id
+        name
+        description
+        clientConfigurations {
+            id
+            name
+        }
+    }
+}
+```
+
+**Variables:**
+
+```json
+{
+    "id": "6911f062534d4b0db1e1ced2",
+    "input": {
+        "name": "Updated Tenant Name",
+        "description": "New description",
+        "clientConfigurations": [
+            {
+                "name": "NEW_API_KEY",
+                "description": "Additional key for new service"
+            }
+        ]
+    }
+}
+```
+
+**⚠️ Note:** Existing API keys are preserved. New keys are appended.
+
+### Deleting Tenants
+
+**UI:**
+
+- Click **"Actions" → "Delete"** on a tenant
+- Confirm deletion
+- This will:
+    - Delete tenant record
+    - Trigger Keycloak client cleanup (async)
+
+**GraphQL:**
+
+```graphql
+mutation DeleteTenant($id: ID!) {
+    deleteTenant(id: $id)
+}
+```
+
+### Retry Failed Creation
+
+If tenant creation fails (status: `ERROR`):
+
+**UI:**
+
+- Click **"Actions" → "Retry Creation"**
+
+**GraphQL:**
+
+```graphql
+mutation RetryTenantCreation($tenantId: ID!) {
+    retryTenantCreation(tenantId: $tenantId)
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. **"Tenant with ID not found"**
+
+**Cause:** Passing MongoDB `_id` instead of `tenantId`
+
+**Solution:** Always use the `tenantId` field (UUID format):
+
+```typescript
+// ✅ Correct
+const id = tenant.tenantId; // "6911f062-534d-4b0d-b1e1-ced2..."
+
+// ❌ Wrong
+const id = tenant.id; // MongoDB ObjectId
+```
+
+#### 2. **"Invalid tenant credentials" (401)**
+
+**Causes:**
+
+- Incorrect `x-tenant-key` encoding
+- Using MongoDB ID instead of `tenantId`
+- Client doesn't exist in Keycloak
+- Client secret is wrong
+
+**Debug Steps:**
+
+```javascript
+// 1. Check encoding
+const decoded = Buffer.from(tenantKey, 'base64').toString();
+console.log('Decoded:', decoded); // Should be "clientId:secret"
+
+// 2. Verify clientId exists
+// Check in Keycloak admin console or reveal key in UI
+
+// 3. Test credentials
+// Use "Reveal" in UI to get correct credentials
+```
+
+#### 3. **Tenant Status Stuck on "PENDING"**
+
+**Causes:**
+
+- Inngest workflow not running
+- Keycloak connection failed
+- Network issues
+
+**Resolution:**
+
+1. Check Inngest dashboard for failed jobs
+2. Verify Keycloak is accessible
+3. Check server logs for errors
+4. Use **"Retry Creation"** if needed
+
+#### 4. **"At least one secret API key is required"**
+
+**Cause:** Trying to create tenant without API keys
+
+**Solution:** Add at least one client configuration:
+
+```json
+{
+    "clientConfigurations": [
+        {
+            "name": "DEFAULT_KEY",
+            "description": "Primary API key"
+        }
+    ]
+}
+```
+
+#### 5. **Environment Tag Not Found**
+
+**Cause:** Invalid or missing environment tag ID
+
+**Solution:**
+
+1. Fetch available tags:
+
+```graphql
+query GetEnvironmentTags($projectId: ID!) {
+    getEnvironmentTags(projectId: $projectId) {
+        id
+        name
+    }
+}
+```
+
+2. Use a valid tag ID in tenant creation
+
+---
+
+## Best Practices
+
+### Security
+
+1. **Never expose client secrets in frontend code**
+    - Store in backend environment variables
+    - Use server-to-server communication
+
+2. **Rotate API keys regularly**
+    - Add new key
+    - Update services to use new key
+    - Revoke old key
+
+3. **Use separate keys per service**
+    - Easier to track usage
+    - Limit blast radius if compromised
+
+### Organization
+
+1. **Use descriptive names**
+
+    ```
+    ✅ "PRODUCTION_WEB_APP"
+    ✅ "STAGING_MOBILE_IOS"
+    ❌ "key1"
+    ❌ "test"
+    ```
+
+2. **Match environment to usage**
+    - Don't use production tenants in development
+    - Create separate tenants per environment
+
+3. **Associate with projects**
+    - Helps with resource tracking
+    - Enables better access control
+
+---
+
+## Additional Resources
+
+- **GraphQL API Documentation**: `/graphql` (GraphiQL interface)
+- **Keycloak Admin Console**: Check configured clients
+- **Inngest Dashboard**: Monitor tenant creation jobs
+- **Server Logs**: Check for detailed error messages
+
+---
+
+## Support
+
+For issues or questions:
+
+1. Check this documentation
+2. Review server logs
+3. Contact your system administrator
+4. Check Keycloak and Inngest status
+
+---