@crownpeak/dqm-react-component 1.0.0

package/BACKEND-API.md

@@ -0,0 +1,1829 @@
+# DQM Backend API - Architecture & Implementation Guide
+
+## Overview
+
+The DQM Backend API provides a **secure proxy layer** between your React application and the Crownpeak DQM API. It enables **centralized credential management** through server-side storage, eliminating the need to expose DQM API keys in the browser.
+
+## Two Operating Modes
+
+### Mode 1: Direct API Key (Development/Testing)
+User provides Crownpeak credentials directly in the widget:
+```
+User → Widget (API Key + Website ID) → Crownpeak DQM API
+```
+**Use Case:** Quick testing, development environments, demos
+
+### Mode 2: Backend Session with SSO (Production - RECOMMENDED)
+User authenticates with YOUR system, backend manages DQM credentials:
+```
+User → Your OAuth/SSO → Your Backend → Retrieves DQM Credentials → Session Token → Widget → Backend Proxy → Crownpeak DQM API
+```
+**Use Case:** Production deployments, enterprise SSO integration, centralized credential management
+
+---
+
+## Mode 2 Architecture (SSO/Backend - RECOMMENDED)
+
+### Complete Authentication Flow
+
+```mermaid
+sequenceDiagram
+   autonumber
+   actor User as 👤 User (Browser)
+   participant Widget as DQM Widget<br/>(React Component)
+   participant Popup as Login Popup Window
+   participant Backend as Your Backend<br/>(Express/Node.js)
+   participant OAuth as OAuth Provider<br/>(Okta/Azure AD/Auth0)
+   participant DB as Your Database<br/>(User Credentials)
+   participant Redis as Redis SessionStore
+   participant DQM as Crownpeak DQM API<br/>(api.crownpeak.net)
+
+   Note over User,DQM: Phase 1: Initial Authentication Request
+   User->>Widget: Opens widget, clicks "Login"
+   activate Widget
+   Widget->>Popup: window.open('/auth/login')
+   activate Popup
+   Note over Popup: Beautiful Material-UI<br/>Login Page<br/>(Built from server-ui/)
+   Popup-->>User: Display: "Sign in with SSO"<br/>or "Direct API Key"
+   deactivate Widget
+
+   Note over User,DQM: Phase 2: OAuth Authorization Flow
+   User->>Popup: Clicks "Sign in with SSO"
+   Popup->>OAuth: Redirect to OAuth authorize URL<br/>?client_id=X&redirect_uri=/auth/callback
+   activate OAuth
+   OAuth-->>User: Display login form
+   User->>OAuth: Enter credentials
+   OAuth->>OAuth: Validate user credentials
+   OAuth->>Popup: Redirect: /auth/callback<br/>?code=xyz&state=abc
+   deactivate OAuth
+   activate Popup
+   Note over Popup: Callback Handler Page<br/>Shows loading spinner
+
+   Note over User,DQM: Phase 3: Token Exchange & Session Creation
+   Popup->>Backend: POST /auth/oauth2/callback<br/>{ code, redirectUri }
+   activate Backend
+   Backend->>OAuth: POST /token<br/>{ grant_type, code,<br/>client_id, client_secret }
+   activate OAuth
+   OAuth-->>Backend: { access_token, ... }
+   deactivate OAuth
+
+   Backend->>OAuth: GET /userinfo<br/>Authorization: Bearer {token}
+   activate OAuth
+   OAuth-->>Backend: { sub: userId, email, ... }
+   deactivate OAuth
+
+   Backend->>DB: SELECT api_key, website_id<br/>WHERE user_id = $userId
+   activate DB
+   Note over DB: Table: user_dqm_credentials<br/>┌──────────┬─────────────┐<br/>│ user_id  │ dqm_api_key │ (ENCRYPTED!)<br/>│          │ website_id  │<br/>└──────────┴─────────────┘
+   DB-->>Backend: { encrypted_api_key,<br/>website_id }
+   deactivate DB
+
+   Backend->>Backend: apiKey = decrypt(encrypted_api_key)
+
+   Backend->>Redis: Create session<br/>sessionStore.create(apiKey,<br/>websiteId, userId)
+   activate Redis
+   Note over Redis: Store session data:<br/>session:{token}<br/>├─ apiKey: "real_key..."<br/>├─ websiteId: "site123"<br/>├─ userId: "user456"<br/>└─ expiresAt: timestamp<br/><br/>TTL: 24 hours
+   Redis-->>Backend: sessionToken
+   deactivate Redis
+
+   Backend-->>Popup: 200 OK<br/>{ sessionToken,<br/>websiteId, userId }
+   deactivate Backend
+
+   Note over User,DQM: Phase 4: Token Propagation to Widget
+   Popup->>Widget: postMessage({<br/>type: 'DQM_AUTH_SUCCESS',<br/>sessionToken, websiteId<br/>})
+   activate Widget
+   Popup->>Popup: window.close()
+   deactivate Popup
+
+   Widget->>Widget: Store in localStorage:<br/>- dqm_sessionToken<br/>- dqm_websiteID<br/>- dqm_sessionType: 'backend'
+   Widget-->>User: Show: "Authenticated ✓"
+   deactivate Widget
+
+   Note over User,DQM: Phase 5: Proxied DQM API Requests
+   User->>Widget: Analyze page quality
+   activate Widget
+   Widget->>Widget: Capture HTML via<br/>optimizeHtmlForAnalysis()
+   Widget->>Backend: POST /dqm/assets<br/>Authorization: Bearer {sessionToken}<br/>{ html, url }
+   activate Backend
+
+   Backend->>Backend: Extract token from header
+   Backend->>Redis: sessionStore.get(token)
+   activate Redis
+   Redis-->>Backend: { apiKey, websiteId, ... }
+   deactivate Redis
+
+   Backend->>Backend: Validate session.expiresAt
+   Backend->>DQM: POST /dqm-cms/v1/assets<br/>x-api-key: {real_api_key}<br/>{ html, url, websiteId }
+   activate DQM
+   DQM-->>Backend: { assetId, analysisState }
+   deactivate DQM
+
+   Backend-->>Widget: { assetId, analysisState }
+   deactivate Backend
+
+   Note over Widget: Poll every 2s for completion
+   loop Until analysisState === 'completed'
+      Widget->>Backend: GET /dqm/assets/{assetId}<br/>Authorization: Bearer {sessionToken}
+      activate Backend
+      Backend->>Redis: Verify session
+      activate Redis
+      Redis-->>Backend: { apiKey }
+      deactivate Redis
+      Backend->>DQM: GET /assets/{assetId}?apiKey=X<br/>x-api-key: {real_api_key}
+      activate DQM
+      DQM-->>Backend: { checkpoints[], totalErrors }
+      deactivate DQM
+      Backend-->>Widget: Analysis data
+      deactivate Backend
+   end
+
+   Widget-->>User: Display quality results<br/>(CategoryCards, Checkpoints)
+   deactivate Widget
+
+   Note over User,DQM: Phase 6: Error Highlighting (Optional)
+   User->>Widget: Click specific checkpoint
+   activate Widget
+   Widget->>Backend: GET /dqm/assets/{assetId}/<br/>pagehighlight/{checkpointId}<br/>Authorization: Bearer {sessionToken}
+   activate Backend
+   Backend->>Redis: Verify session
+   activate Redis
+   Redis-->>Backend: { apiKey }
+   deactivate Redis
+   Backend->>DQM: GET /assets/{assetId}/<br/>pagehighlight/{checkpointId}<br/>x-api-key: {real_api_key}
+   activate DQM
+   DQM-->>Backend: HTML with .astError classes
+   deactivate DQM
+   Backend-->>Widget: Highlighted HTML
+   deactivate Backend
+   Widget->>Widget: Render in ShadowDOMRenderer<br/>with IntersectionObserver
+   Widget-->>User: Show highlighted errors
+   deactivate Widget
+
+   Note over User,DQM: Security: API key never exposed to browser!<br/>All requests proxied through backend with session token.
+```
+
+### Key Concepts
+
+**🔐 Your OAuth Provider = Your Authentication System**
+- This is NOT Crownpeak OAuth
+- This is YOUR company's SSO system (Okta, Azure AD, Auth0, Keycloak, custom OAuth, etc.)
+- Users log in with THEIR work credentials
+- Example: `user@yourcompany.com` + password/MFA
+
+**🗄️ Your Database = DQM Credential Storage**
+- You store a mapping: `userId` → `{ dqmApiKey, dqmWebsiteId }`
+- When user logs in via SSO, backend looks up their DQM credentials
+- Users never see or enter Crownpeak API keys
+- Admin interface needed for initial credential setup
+
+**🎟️ Session Token = Temporary Access Key**
+- Backend creates this after successful SSO authentication
+- Widget uses this for all DQM requests
+- Maps to real DQM credentials server-side
+- Expires after 24 hours (configurable)
+
+
+
+
+---
+
+## Implementation Steps
+
+### Step 1: Database Schema for User Credentials
+
+Create a table to store each user's DQM credentials:
+
+```sql
+-- PostgreSQL Example
+CREATE TABLE user_dqm_credentials (
+  user_id UUID PRIMARY KEY,
+  api_key TEXT NOT NULL,           -- ⚠️ MUST BE ENCRYPTED!
+  website_id VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+-- Add indexes for performance
+CREATE INDEX idx_user_dqm_user_id ON user_dqm_credentials(user_id);
+
+-- Audit trail (optional but recommended)
+CREATE TABLE dqm_credential_audit (
+  id SERIAL PRIMARY KEY,
+  user_id UUID NOT NULL,
+  action VARCHAR(50) NOT NULL, -- 'created', 'updated', 'deleted', 'accessed'
+  performed_by UUID,           -- Admin user who made the change
+  timestamp TIMESTAMP DEFAULT NOW(),
+  FOREIGN KEY (user_id) REFERENCES users(id)
+);
+```
+
+⚠️ **CRITICAL SECURITY**: Always encrypt `api_key` before storing!
+
+```typescript
+// Example encryption (using Node.js crypto)
+import crypto from 'crypto';
+
+const ENCRYPTION_KEY = Buffer.from(process.env.ENCRYPTION_KEY!, 'hex'); // 32 bytes
+const ALGORITHM = 'aes-256-gcm';
+
+export function encrypt(text: string): string {
+  const iv = crypto.randomBytes(16);
+  const cipher = crypto.createCipheriv(ALGORITHM, ENCRYPTION_KEY, iv);
+  let encrypted = cipher.update(text, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+  const authTag = cipher.getAuthTag();
+  return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted}`;
+}
+
+export function decrypt(encrypted: string): string {
+  const [ivHex, authTagHex, encryptedText] = encrypted.split(':');
+  const iv = Buffer.from(ivHex, 'hex');
+  const authTag = Buffer.from(authTagHex, 'hex');
+  const decipher = crypto.createDecipheriv(ALGORITHM, ENCRYPTION_KEY, iv);
+  decipher.setAuthTag(authTag);
+  let decrypted = decipher.update(encryptedText, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+  return decrypted;
+}
+
+// Generate encryption key (run once, store in .env):
+// node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+### Step 2: Implement OAuth Callback Handler
+
+Edit `server/routes/auth.ts` and implement the callback handler:
+
+```typescript
+import { Router, Request, Response } from 'express';
+import { sessionStore } from '../services/sessionStore.js';
+import { yourDB } from '../services/database.js'; // Your database service
+import { encrypt, decrypt } from '../utils/crypto.js'; // Your encryption utils
+
+const authRouter = Router();
+
+authRouter.post('/oauth2/callback', async (req: Request, res: Response) => {
+  try {
+    const { code, redirectUri } = req.body;
+
+    if (!code || !redirectUri) {
+      return res.status(400).json({
+        error: true,
+        message: 'Missing required parameters: code and redirectUri',
+      });
+    }
+
+    // ============================================
+    // STEP 1: Exchange code for access token
+    // ============================================
+    const tokenResponse = await fetch(process.env.OAUTH_TOKEN_URL!, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        client_id: process.env.OAUTH_CLIENT_ID!,
+        client_secret: process.env.OAUTH_CLIENT_SECRET!,
+      }),
+    });
+
+    if (!tokenResponse.ok) {
+      const errorData = await tokenResponse.text();
+      console.error('[Auth] Token exchange failed:', errorData);
+      throw new Error('Failed to exchange authorization code for access token');
+    }
+
+    const tokenData = await tokenResponse.json();
+    const accessToken = tokenData.access_token;
+
+    // ============================================
+    // STEP 2: Get user info from YOUR OAuth provider
+    // ============================================
+    const userInfoResponse = await fetch(process.env.OAUTH_USERINFO_URL!, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    if (!userInfoResponse.ok) {
+      throw new Error('Failed to fetch user info from OAuth provider');
+    }
+
+    const userInfo = await userInfoResponse.json();
+    const userId = userInfo.sub || userInfo.id || userInfo.userId;
+
+    if (!userId) {
+      throw new Error('User ID not found in OAuth response');
+    }
+
+    console.log(`[Auth] OAuth success for user: ${userId}`);
+
+    // ============================================
+    // STEP 3: Retrieve DQM credentials from YOUR database
+    // ============================================
+    const credentialsResult = await yourDB.query(
+      'SELECT api_key, website_id FROM user_dqm_credentials WHERE user_id = $1',
+      [userId]
+    );
+
+    if (!credentialsResult || credentialsResult.rows.length === 0) {
+      console.warn(`[Auth] No DQM credentials found for user ${userId}`);
+      return res.status(404).json({
+        error: true,
+        message: 'DQM credentials not configured for this user. Please contact your administrator.',
+        code: 'CREDENTIALS_NOT_FOUND',
+      });
+    }
+
+    const { api_key: encryptedApiKey, website_id: websiteId } = credentialsResult.rows[0];
+
+    // ============================================
+    // STEP 4: Decrypt API key and create session
+    // ============================================
+    const apiKey = decrypt(encryptedApiKey);
+
+    // Optional: Validate credentials with Crownpeak DQM API
+    // const isValid = await validateDQMCredentials(apiKey, websiteId);
+    // if (!isValid) {
+    //   return res.status(401).json({
+    //     error: true,
+    //     message: 'DQM credentials are invalid. Please contact your administrator.',
+    //   });
+    // }
+
+    // Create session in Redis/SessionStore
+    const sessionToken = await sessionStore.create(apiKey, websiteId, userId);
+
+    console.log(`[Auth] Created session ${sessionToken} for user ${userId}`);
+
+    // ============================================
+    // STEP 5: Return session token to widget
+    // ============================================
+    res.json({
+      sessionToken,
+      websiteId,
+      userId, // Optional: for display purposes
+    });
+  } catch (error: any) {
+    console.error('[Auth] OAuth2 callback error:', error);
+    res.status(401).json({
+      error: true,
+      message: error.message || 'OAuth2 authentication failed',
+      code: 'OAUTH_ERROR',
+    });
+  }
+});
+
+export { authRouter };
+```
+
+### Step 3: Configure Environment Variables
+
+Create `.env` file in your backend:
+
+```bash
+# ==================================
+# YOUR OAuth/SSO Configuration
+# ==================================
+OAUTH_CLIENT_ID=your-oauth-client-id
+OAUTH_CLIENT_SECRET=your-oauth-client-secret
+OAUTH_AUTHORIZE_URL=https://your-oauth-provider.com/oauth2/authorize
+OAUTH_TOKEN_URL=https://your-oauth-provider.com/oauth2/token
+OAUTH_USERINFO_URL=https://your-oauth-provider.com/oauth2/userinfo
+
+# ==================================
+# DQM Backend Configuration
+# ==================================
+PORT=3001
+REDIS_URL=redis://localhost:6379
+
+# ==================================
+# Security
+# ==================================
+ENCRYPTION_KEY=your-32-byte-hex-key-here  # Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+SESSION_TTL=86400  # 24 hours in seconds
+
+# ==================================
+# CORS
+# ==================================
+CORS_ORIGINS=http://localhost:3000,https://yourdomain.com
+
+# ==================================
+# Database (example for PostgreSQL)
+# ==================================
+DATABASE_URL=postgresql://user:password@localhost:5432/yourdb
+```
+
+### Step 4: Configure Auth UI
+
+Edit `server-ui/.env`:
+
+```bash
+# Point to YOUR OAuth provider
+VITE_OAUTH_CLIENT_ID=your-oauth-client-id
+VITE_OAUTH_AUTHORIZE_URL=https://your-oauth-provider.com/oauth2/authorize
+VITE_API_BASE_URL=http://localhost:3001
+```
+
+### Step 5: Admin Interface for Credential Management
+
+Create an admin interface where you (or admins) can configure DQM credentials for users:
+
+```tsx
+// Example: Admin Settings Component
+import { useState, useEffect } from 'react';
+
+function UserDQMSettings({ userId }: { userId: string }) {
+  const [apiKey, setApiKey] = useState('');
+  const [websiteId, setWebsiteId] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [success, setSuccess] = useState(false);
+
+  // Load existing credentials
+  useEffect(() => {
+    fetch(`/api/admin/users/${userId}/dqm-credentials`, {
+      headers: {
+        Authorization: `Bearer ${yourAdminToken}`,
+      },
+    })
+      .then((res) => res.json())
+      .then((data) => {
+        if (data.websiteId) {
+          setWebsiteId(data.websiteId);
+          // Don't load API key for security
+        }
+      });
+  }, [userId]);
+
+  const handleSave = async () => {
+    setLoading(true);
+    setError('');
+    setSuccess(false);
+
+    try {
+      const response = await fetch(`/api/admin/users/${userId}/dqm-credentials`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${yourAdminToken}`,
+        },
+        body: JSON.stringify({
+          apiKey,
+          websiteId,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(errorData.message || 'Failed to save credentials');
+      }
+
+      setSuccess(true);
+      setApiKey(''); // Clear for security
+    } catch (err: any) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="dqm-settings-form">
+      <h3>DQM Integration Settings</h3>
+      <p>Configure Crownpeak DQM credentials for this user.</p>
+
+      {error && <div className="error-message">{error}</div>}
+      {success && <div className="success-message">Credentials saved successfully!</div>}
+
+      <div className="form-group">
+        <label htmlFor="apiKey">Crownpeak API Key</label>
+        <input
+          id="apiKey"
+          type="password"
+          value={apiKey}
+          onChange={(e) => setApiKey(e.target.value)}
+          placeholder="Enter new API key (leave blank to keep existing)"
+          autoComplete="off"
+        />
+        <small>This will be encrypted before storage</small>
+      </div>
+
+      <div className="form-group">
+        <label htmlFor="websiteId">Website ID</label>
+        <input
+          id="websiteId"
+          value={websiteId}
+          onChange={(e) => setWebsiteId(e.target.value)}
+          placeholder="e.g., my-website-id"
+        />
+      </div>
+
+      <button onClick={handleSave} disabled={loading}>
+        {loading ? 'Saving...' : 'Save Credentials'}
+      </button>
+    </div>
+  );
+}
+
+export default UserDQMSettings;
+```
+
+Backend endpoint:
+
+```typescript
+// Your backend admin API
+app.post('/api/admin/users/:userId/dqm-credentials', 
+  authenticateAdmin,  // Middleware to ensure user is admin
+  async (req, res) => {
+    const { userId } = req.params;
+    const { apiKey, websiteId } = req.body;
+
+    if (!websiteId) {
+      return res.status(400).json({ error: 'Website ID is required' });
+    }
+
+    try {
+      // Optional: Validate credentials with Crownpeak before saving
+      if (apiKey) {
+        const isValid = await validateDQMCredentials(apiKey, websiteId);
+        if (!isValid) {
+          return res.status(400).json({ 
+            error: 'Invalid DQM credentials. Please check API key and Website ID.' 
+          });
+        }
+
+        // Encrypt API key
+        const encryptedKey = encrypt(apiKey);
+
+        // Store in database
+        await db.query(
+          `INSERT INTO user_dqm_credentials (user_id, api_key, website_id, updated_at)
+           VALUES ($1, $2, $3, NOW())
+           ON CONFLICT (user_id) 
+           DO UPDATE SET api_key = $2, website_id = $3, updated_at = NOW()`,
+          [userId, encryptedKey, websiteId]
+        );
+
+        // Audit trail
+        await db.query(
+          `INSERT INTO dqm_credential_audit (user_id, action, performed_by, timestamp)
+           VALUES ($1, 'updated', $2, NOW())`,
+          [userId, req.user.id]
+        );
+      } else {
+        // Update only website ID (keep existing API key)
+        await db.query(
+          `UPDATE user_dqm_credentials 
+           SET website_id = $1, updated_at = NOW()
+           WHERE user_id = $2`,
+          [websiteId, userId]
+        );
+      }
+
+      res.json({ success: true });
+    } catch (error: any) {
+      console.error('[Admin] Failed to save DQM credentials:', error);
+      res.status(500).json({ 
+        error: 'Failed to save credentials', 
+        message: error.message 
+      });
+    }
+  }
+);
+
+async function validateDQMCredentials(apiKey: string, websiteId: string): Promise<boolean> {
+  try {
+    const response = await fetch(
+      `https://api.crownpeak.net/dqm-cms/v1/websites/${websiteId}`,
+      {
+        headers: {
+          'x-api-key': apiKey,
+        },
+      }
+    );
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+```
+
+### Step 6: Widget Configuration
+
+In your React app where you embed the DQM Widget:
+
+```tsx
+import { DQMSidebar } from '@crownpeak/dqm-react-component';
+import { useState, useEffect } from 'react';
+
+function MyApp() {
+  const [isDQMOpen, setIsDQMOpen] = useState(false);
+
+  const handleOpenDQM = () => {
+    // Check if user already has a session token
+    const existingToken = localStorage.getItem('dqm_sessionToken');
+    const sessionType = localStorage.getItem('dqm_sessionType');
+
+    if (existingToken && sessionType === 'backend') {
+      // User is already authenticated, open widget directly
+      setIsDQMOpen(true);
+    } else {
+      // Open SSO login page in popup
+      const authWindow = window.open(
+        'http://localhost:3001/auth/login',
+        'DQM Login',
+        'width=500,height=700,scrollbars=yes,resizable=yes'
+      );
+
+      if (!authWindow) {
+        alert('Please enable popups to log in');
+        return;
+      }
+
+      // Listen for authentication success
+      const handleMessage = (event: MessageEvent) => {
+        // Verify origin for security
+        if (event.origin !== 'http://localhost:3001') {
+          return;
+        }
+
+        if (event.data.type === 'DQM_AUTH_SUCCESS') {
+          const { sessionToken, websiteId } = event.data;
+
+          // Store session token in localStorage
+          localStorage.setItem('dqm_sessionToken', sessionToken);
+          localStorage.setItem('dqm_websiteID', websiteId);
+          localStorage.setItem('dqm_sessionType', 'backend');
+
+          // Close auth window
+          authWindow.close();
+
+          // Open widget
+          setIsDQMOpen(true);
+
+          // Remove event listener
+          window.removeEventListener('message', handleMessage);
+        } else if (event.data.type === 'DQM_AUTH_ERROR') {
+          alert('Authentication failed: ' + event.data.error);
+          authWindow.close();
+          window.removeEventListener('message', handleMessage);
+        }
+      };
+
+      window.addEventListener('message', handleMessage);
+    }
+  };
+
+  return (
+    <div className="app">
+      <header>
+        <h1>My Application</h1>
+        <button onClick={handleOpenDQM} className="dqm-button">
+          ✨ Check Quality with DQM
+        </button>
+      </header>
+
+      <main>
+        {/* Your app content */}
+      </main>
+
+      <DQMSidebar
+        open={isDQMOpen}
+        onClose={() => setIsDQMOpen(false)}
+        onOpen={() => setIsDQMOpen(true)}
+        config={{
+          backendUrl: 'http://localhost:3001',  // Your backend proxy
+          useBackend: true,                      // Enable backend mode
+          useLocalStorage: true,                 // Store session token
+        }}
+        onAuthSuccess={(credentials) => {
+          console.log('DQM authenticated:', credentials.sessionType);
+        }}
+        onAuthError={(error) => {
+          console.error('DQM auth error:', error);
+          // Clear invalid session
+          localStorage.removeItem('dqm_sessionToken');
+          localStorage.removeItem('dqm_websiteID');
+          localStorage.removeItem('dqm_sessionType');
+        }}
+      />
+    </div>
+  );
+}
+
+export default MyApp;
+```
+
+
+
+
+---
+
+## API Endpoints Reference
+
+Your backend must implement these endpoints for the widget to communicate with Crownpeak DQM API.
+
+### Authentication Endpoints
+
+#### 1. Direct Credentials Login (Fallback Mode)
+
+**Endpoint:** `POST /auth/login`
+
+**Description:** User provides API Key and Website ID directly. Backend validates and issues session token.
+
+**Request:**
+```json
+{
+  "apiKey": "user_crownpeak_api_key",
+  "websiteId": "user_website_id"
+}
+```
+
+**Response (Success - 200):**
+```json
+{
+  "sessionToken": "unique_session_token_or_jwt",
+  "websiteId": "user_website_id"
+}
+```
+
+**Response (Error - 401):**
+```json
+{
+  "error": true,
+  "message": "Invalid credentials or authentication failed"
+}
+```
+
+#### 2. Backend Session Authentication
+
+**Endpoint:** `POST /auth/token`
+
+**Description:** User already authenticated via your backend's session/cookie. Backend issues DQM session token.
+
+**Headers:**
+```
+Cookie: your_session_cookie
+```
+
+**Response (Success - 200):**
+```json
+{
+  "sessionToken": "unique_session_token",
+  "websiteId": "user_website_id"
+}
+```
+
+**Response (Error - 401):**
+```json
+{
+  "error": true,
+  "message": "Not authenticated"
+}
+```
+
+#### 3. OAuth2 Callback (Recommended for SSO)
+
+**Endpoint:** `POST /auth/oauth2/callback`
+
+**Description:** Process OAuth2 authorization code and issue session token.
+
+**Request:**
+```json
+{
+  "code": "oauth2_authorization_code",
+  "redirectUri": "https://your-backend.com/auth/callback"
+}
+```
+
+**Response (Success - 200):**
+```json
+{
+  "sessionToken": "unique_session_token",
+  "websiteId": "user_website_id",
+  "userId": "user123"  // Optional
+}
+```
+
+**Response (Error - 401):**
+```json
+{
+  "error": true,
+  "message": "OAuth2 token exchange failed",
+  "code": "OAUTH_ERROR"
+}
+```
+
+**Response (Error - 404):**
+```json
+{
+  "error": true,
+  "message": "DQM credentials not configured for this user. Please contact your administrator.",
+  "code": "CREDENTIALS_NOT_FOUND"
+}
+```
+
+---
+
+### DQM Proxy Endpoints
+
+All DQM API calls are proxied through your backend when in Backend Mode.
+
+#### 4. Start HTML Analysis
+
+**Endpoint:** `POST /dqm/assets`
+
+**Description:** Proxy for Crownpeak DQM API - Start HTML analysis.
+
+**Headers:**
+```
+Authorization: Bearer <sessionToken>
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "html": "<html>...</html>",
+  "url": "https://example.com/page",
+  "websiteId": "optional_if_backend_knows"
+}
+```
+
+**Response (Success - 200):**
+```json
+{
+  "assetId": "generated_asset_id",
+  "analysisState": "analyzing",
+  "totalCheckpoints": 150
+}
+```
+
+**Backend Implementation:**
+```typescript
+app.post('/dqm/assets', authenticateSession, async (req, res) => {
+  const { apiKey, websiteId } = req.session;  // From session store
+  
+  const response = await fetch('https://api.crownpeak.net/dqm-cms/v1/assets', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+    },
+    body: JSON.stringify({
+      ...req.body,
+      websiteId, // Ensure correct websiteId
+    }),
+  });
+  
+  const data = await response.json();
+  res.json(data);
+});
+```
+
+#### 5. Get Analysis Status (Polling)
+
+**Endpoint:** `GET /dqm/assets/:assetId`
+
+**Description:** Poll analysis status and get results when complete.
+
+**Headers:**
+```
+Authorization: Bearer <sessionToken>
+```
+
+**Response (Success - 200):**
+```json
+{
+  "assetId": "asset_id",
+  "checkpoints": [
+    {
+      "checkpointId": "cp1",
+      "name": "Heading Structure",
+      "category": "Accessibility",
+      "severity": "high",
+      "failedCount": 3,
+      "passedCount": 12,
+      "canHighlight": { "page": true, "source": true }
+    }
+  ],
+  "totalCheckpoints": 150,
+  "totalErrors": 42
+}
+```
+
+**Backend Implementation:**
+```typescript
+app.get('/dqm/assets/:assetId', authenticateSession, async (req, res) => {
+  const { apiKey } = req.session;
+  const { assetId } = req.params;
+  
+  const response = await fetch(
+    `https://api.crownpeak.net/dqm-cms/v1/assets/${assetId}?apiKey=${apiKey}`,
+    {
+      headers: { 'x-api-key': apiKey },
+    }
+  );
+  
+  const data = await response.json();
+  res.json(data);
+});
+```
+
+#### 6. Get Highlighted HTML (All Errors)
+
+**Endpoint:** `GET /dqm/assets/:assetId/pagehighlight/all`
+
+**Description:** Get HTML with all errors highlighted using CSS classes.
+
+**Headers:**
+```
+Authorization: Bearer <sessionToken>
+```
+
+**Response (Success - 200):**
+```html
+<html>
+  <body>
+    <h1 class="astHighlightFull astError" data-checkpoint="cp1">
+      Heading text
+    </h1>
+    <!-- More highlighted HTML -->
+  </body>
+</html>
+```
+
+**Backend Implementation:**
+```typescript
+app.get('/dqm/assets/:assetId/pagehighlight/all', authenticateSession, async (req, res) => {
+  const { apiKey } = req.session;
+  const { assetId } = req.params;
+  
+  const response = await fetch(
+    `https://api.crownpeak.net/dqm-cms/v1/assets/${assetId}/pagehighlight/all?apiKey=${apiKey}`,
+    {
+      headers: { 'x-api-key': apiKey },
+    }
+  );
+  
+  const html = await response.text();
+  res.setHeader('Content-Type', 'text/html');
+  res.send(html);
+});
+```
+
+#### 7. Get Highlighted HTML (Specific Checkpoint)
+
+**Endpoint:** `GET /dqm/assets/:assetId/pagehighlight/:checkpointId`
+
+**Description:** Get HTML with only specific checkpoint errors highlighted.
+
+**Headers:**
+```
+Authorization: Bearer <sessionToken>
+```
+
+**Response (Success - 200):**
+```html
+<html>
+  <body>
+    <h1 class="astHighlightStart astError">Heading</h1>
+  </body>
+</html>
+```
+
+**Backend Implementation:**
+```typescript
+app.get('/dqm/assets/:assetId/pagehighlight/:checkpointId', authenticateSession, async (req, res) => {
+  const { apiKey } = req.session;
+  const { assetId, checkpointId } = req.params;
+  
+  const response = await fetch(
+    `https://api.crownpeak.net/dqm-cms/v1/assets/${assetId}/pagehighlight/${checkpointId}?apiKey=${apiKey}`,
+    {
+      headers: { 'x-api-key': apiKey },
+    }
+  );
+  
+  const html = await response.text();
+  res.setHeader('Content-Type', 'text/html');
+  res.send(html);
+});
+```
+
+---
+
+## Session Management
+
+### Session Store Interface
+
+```typescript
+interface Session {
+  apiKey: string;       // Real Crownpeak API key
+  websiteId: string;    // Website ID
+  userId?: string;      // Your user identifier
+  expiresAt: number;    // Unix timestamp
+}
+
+interface SessionStore {
+  create(apiKey: string, websiteId: string, userId?: string): Promise<string>;
+  get(token: string): Promise<Session | null>;
+  delete(token: string): Promise<void>;
+  refresh(token: string): Promise<void>;
+}
+```
+
+### Redis Implementation (Recommended)
+
+```typescript
+import Redis from 'ioredis';
+import crypto from 'crypto';
+
+const redis = new Redis(process.env.REDIS_URL);
+const SESSION_TTL = 86400; // 24 hours
+
+export const sessionStore = {
+  async create(apiKey: string, websiteId: string, userId?: string): Promise<string> {
+    const token = crypto.randomBytes(32).toString('hex');
+    const session: Session = {
+      apiKey,
+      websiteId,
+      userId,
+      expiresAt: Date.now() + SESSION_TTL * 1000,
+    };
+    
+    await redis.setex(
+      `session:${token}`,
+      SESSION_TTL,
+      JSON.stringify(session)
+    );
+    
+    return token;
+  },
+
+  async get(token: string): Promise<Session | null> {
+    const data = await redis.get(`session:${token}`);
+    if (!data) return null;
+    
+    const session: Session = JSON.parse(data);
+    
+    // Check expiration
+    if (session.expiresAt < Date.now()) {
+      await this.delete(token);
+      return null;
+    }
+    
+    return session;
+  },
+
+  async delete(token: string): Promise<void> {
+    await redis.del(`session:${token}`);
+  },
+
+  async refresh(token: string): Promise<void> {
+    const session = await this.get(token);
+    if (session) {
+      session.expiresAt = Date.now() + SESSION_TTL * 1000;
+      await redis.setex(
+        `session:${token}`,
+        SESSION_TTL,
+        JSON.stringify(session)
+      );
+    }
+  },
+};
+```
+
+### Authentication Middleware
+
+```typescript
+import { Request, Response, NextFunction } from 'express';
+
+interface AuthenticatedRequest extends Request {
+  session?: {
+    apiKey: string;
+    websiteId: string;
+    userId?: string;
+  };
+}
+
+export async function authenticateSession(
+  req: AuthenticatedRequest,
+  res: Response,
+  next: NextFunction
+) {
+  try {
+    // Extract token from Authorization header
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return res.status(401).json({
+        error: true,
+        message: 'Missing or invalid Authorization header',
+      });
+    }
+
+    const token = authHeader.substring(7); // Remove 'Bearer '
+
+    // Get session from store
+    const session = await sessionStore.get(token);
+    if (!session) {
+      return res.status(401).json({
+        error: true,
+        message: 'Invalid or expired session token',
+      });
+    }
+
+    // Attach session to request
+    req.session = session;
+
+    // Optional: Refresh session TTL on activity
+    await sessionStore.refresh(token);
+
+    next();
+  } catch (error) {
+    console.error('[Auth] Session verification failed:', error);
+    res.status(500).json({
+      error: true,
+      message: 'Internal server error during authentication',
+    });
+  }
+}
+```
+
+---
+
+## Security Best Practices
+
+### 1. Encryption at Rest
+
+Always encrypt API keys in database:
+
+```typescript
+// Generate encryption key (run once):
+// node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+// Store in .env:
+ENCRYPTION_KEY=your-64-character-hex-string-here
+```
+
+### 2. HTTPS Only
+
+```typescript
+// Redirect HTTP to HTTPS in production
+app.use((req, res, next) => {
+  if (process.env.NODE_ENV === 'production' && !req.secure) {
+    return res.redirect(`https://${req.headers.host}${req.url}`);
+  }
+  next();
+});
+```
+
+### 3. CORS Configuration
+
+```typescript
+import cors from 'cors';
+
+const allowedOrigins = process.env.CORS_ORIGINS?.split(',') || [];
+
+app.use(cors({
+   origin: (origin, callback) => {
+    if (!origin || allowedOrigins.includes(origin)) {
+      callback(null, true);
+    } else {
+      callback(new Error('Not allowed by CORS'));
+    }
+  },
+  credentials: true,
+}));
+```
+
+### 4. Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // 5 requests per window
+  message: 'Too many authentication attempts, please try again later',
+});
+
+app.use('/auth', authLimiter);
+```
+
+### 5. Input Validation
+
+```typescript
+import { body, validationResult } from 'express-validator';
+
+app.post('/auth/login',
+  body('apiKey').isString().trim().notEmpty(),
+  body('websiteId').isString().trim().notEmpty(),
+  async (req, res) => {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+    // ... proceed with login
+  }
+);
+```
+
+### 6. Audit Logging
+
+```typescript
+async function logAuthEvent(
+  userId: string,
+  action: string,
+  success: boolean,
+  ipAddress: string
+) {
+  await db.query(
+    `INSERT INTO auth_audit_log (user_id, action, success, ip_address, timestamp)
+     VALUES ($1, $2, $3, $4, NOW())`,
+    [userId, action, success, ipAddress]
+  );
+}
+
+// Usage:
+await logAuthEvent(userId, 'oauth_login', true, req.ip);
+```
+
+---
+
+## Alternative: Shared Organizational Credentials
+
+If you don't want per-user credentials, use a **single organization-wide API key**:
+
+```typescript
+// All users share same DQM credentials
+authRouter.post('/oauth2/callback', async (req, res) => {
+  // ... OAuth validation ...
+  
+  // Use organization-wide credentials from environment
+  const apiKey = process.env.DQM_ORG_API_KEY!;
+  const websiteId = process.env.DQM_ORG_WEBSITE_ID!;
+  
+  const sessionToken = await sessionStore.create(apiKey, websiteId, userId);
+  
+  res.json({ sessionToken, websiteId });
+});
+```
+
+**Pros:**
+- ✅ Simpler setup - no per-user credential management
+- ✅ No database schema needed
+- ✅ Easier admin maintenance
+
+**Cons:**
+- ❌ All users share same DQM analysis context
+- ❌ Cannot track usage per user
+- ❌ Cannot have different permissions per user
+
+---
+
+## Testing
+
+### Test OAuth Flow
+
+```bash
+# 1. Start backend
+npm run start:server
+
+# 2. Open login page
+open http://localhost:3001/auth/login
+
+# 3. Click "Sign in with SSO"
+# Should redirect to your OAuth provider
+
+# 4. After auth, check callback
+# Should exchange code for token
+# Should create session in Redis
+# Should return sessionToken
+```
+
+### Test Direct Login
+
+```bash
+curl -X POST http://localhost:3001/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "apiKey": "your_test_api_key",
+    "websiteId": "your_test_website_id"
+  }'
+
+# Expected response:
+# {"sessionToken":"abc123...","websiteId":"your_test_website_id"}
+```
+
+### Test DQM Proxy
+
+```bash
+# Get session token first
+TOKEN="your_session_token_here"
+
+# Start analysis
+curl -X POST http://localhost:3001/dqm/assets \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "html": "<html><body><h1>Test</h1></body></html>",
+    "url": "https://example.com"
+  }'
+
+# Poll status
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:3001/dqm/assets/ASSET_ID_HERE
+```
+
+---
+
+## Deployment Checklist
+
+- [ ] Implement OAuth callback handler in `server/routes/auth.ts`
+- [ ] Create database schema for `user_dqm_credentials`
+- [ ] Generate encryption key and store in environment
+- [ ] Configure OAuth provider (client ID, secret, URLs)
+- [ ] Set up Redis (local, Redis Cloud, AWS ElastiCache)
+- [ ] Build all components: `npm run build`
+- [ ] Configure CORS for production domains
+- [ ] Enable HTTPS (Let's Encrypt, AWS Certificate Manager)
+- [ ] Add rate limiting to auth endpoints
+- [ ] Set up audit logging
+- [ ] Test complete SSO flow end-to-end
+- [ ] Test direct login fallback
+- [ ] Monitor backend logs for errors
+- [ ] Document process for users/admins
+
+---
+
+## Benefits of Backend Mode
+
+✅ **Security**
+- API keys never exposed in browser
+- Encrypted storage in database
+- Server-side request signing
+- Audit trail of all requests
+
+✅ **Centralized Management**
+- Admin can update credentials for all users
+- Single point for credential rotation
+- Per-user or organization-wide credentials
+- Consistent credential lifecycle
+
+✅ **SSO Integration**
+- Seamless login with existing user system
+- No separate credential management for users
+- Consistent UX with your application
+- Support for enterprise identity providers
+
+✅ **Scalability**
+- Redis session store for high availability
+- Horizontal scaling support
+- Session sharing across instances
+- Automatic session cleanup
+
+✅ **Compliance**
+- Meet security requirements
+- Data encryption at rest and in transit
+- Access control and permissions
+- Detailed audit logs
+
+---
+
+## Support & Resources
+
+- **Crownpeak DQM API**: https://docs.crownpeak.com/dqm-api
+- **Component Source**: `src/DQMSidebar.tsx`
+- **Auth UI Source**: `server-ui/src/`
+- **Backend Source**: `server/`
+- **Examples**: See `EXAMPLES.md` for integration patterns
+
+
+
+---
+
+### 2. Backend Session Authentication
+
+**Endpoint:** `POST /auth/token`
+
+**Description:** User is already authenticated via your backend's session/cookie system. Backend issues a DQM session token based on current user session.
+
+**Request:**
+```json
+{}
+```
+
+**Headers:**
+```
+Cookie: your_session_cookie
+```
+
+**Response (Success - 200):**
+```json
+{
+  "sessionToken": "unique_session_token_or_jwt",
+  "websiteId": "user_website_id" // Optional
+}
+```
+
+**Response (Error - 401):**
+```json
+{
+  "message": "Not authenticated"
+}
+```
+
+**Notes:**
+- Uses existing user session (cookies, JWT, etc.)
+- Backend determines user identity and associated DQM credentials
+- Useful when user is already logged into your platform
+
+---
+
+### 3. OAuth2 Callback
+
+**Endpoint:** `POST /auth/oauth2/callback`
+
+**Description:** Process OAuth2 authorization code and issue session token.
+
+**Request:**
+```json
+{
+  "code": "oauth2_authorization_code",
+  "redirectUri": "https://your-app.com/oauth-callback"
+}
+```
+
+**Response (Success - 200):**
+```json
+{
+  "sessionToken": "unique_session_token_or_jwt",
+  "websiteId": "user_website_id" // Optional
+}
+```
+
+**Response (Error - 401):**
+```json
+{
+  "message": "OAuth2 token exchange failed"
+}
+```
+
+**Notes:**
+- Backend exchanges authorization code for access token with OAuth2 provider
+- Retrieves user's DQM credentials from OAuth2 provider or your database
+- Issues session token for DQM component
+
+---
+
+## DQM API Proxy Endpoints
+
+When in Backend Mode, **ALL** DQM API calls are proxied through your backend. The component will use `config.authBackendUrl` as the base URL instead of calling Crownpeak DQM API directly.
+
+### 4. Start Analysis
+
+**Endpoint:** `POST /dqm/assets`
+
+**Description:** Proxy for Crownpeak DQM API `POST /assets` - Start HTML analysis.
+
+**Request Headers:**
+```
+Authorization: Bearer <sessionToken>
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "html": "<html>...</html>",
+  "url": "https://example.com/page",
+  "websiteId": "optional_if_backend_knows"
+}
+```
+
+**Response (Success - 200):**
+```json
+{
+  "assetId": "generated_asset_id",
+  "analysisState": "analyzing"
+}
+```
+
+**Backend Implementation:**
+1. Verify session token and retrieve real API key + websiteId
+2. Call Crownpeak DQM API: `POST https://api.crownpeak.net/dqm-cms/v1/assets`
+   - Headers: `x-api-key: <real_api_key>`
+   - Body: Same as client request
+3. Return response to client
+
+---
+
+### 5. Get Analysis Status
+
+**Endpoint:** `GET /dqm/assets/{assetId}`
+
+**Description:** Proxy for Crownpeak DQM API `GET /assets/{assetId}` - Poll analysis status.
+
+**Request Headers:**
+```
+Authorization: Bearer <sessionToken>
+```
+
+**Response (Success - 200):**
+```json
+{
+  "assetId": "asset_id",
+  "analysisState": "completed",
+  "checkpoints": [...],
+  "totalErrors": 42,
+  // ... full analysis data
+}
+```
+
+**Backend Implementation:**
+1. Verify session token and retrieve real API key
+2. Call Crownpeak DQM API: `GET https://api.crownpeak.net/dqm-cms/v1/assets/{assetId}?apiKey=<real_api_key>`
+3. Return response to client
+
+---
+
+### 6. Get Highlighted HTML (All Errors)
+
+**Endpoint:** `GET /dqm/assets/{assetId}/pagehighlight/all`
+
+**Description:** Proxy for Crownpeak DQM API - Get HTML with all errors highlighted.
+
+**Request Headers:**
+```
+Authorization: Bearer <sessionToken>
+```
+
+**Response (Success - 200):**
+```html
+<html>
+  <!-- HTML with .astHighlightFull, .astError classes -->
+</html>
+```
+
+**Backend Implementation:**
+1. Verify session token and retrieve real API key
+2. Call Crownpeak DQM API: `GET https://api.crownpeak.net/dqm-cms/v1/assets/{assetId}/pagehighlight/all?apiKey=<real_api_key>`
+3. Return HTML response to client
+
+---
+
+### 7. Get Highlighted HTML (Specific Checkpoint)
+
+**Endpoint:** `GET /dqm/assets/{assetId}/pagehighlight/{checkpointId}`
+
+**Description:** Proxy for Crownpeak DQM API - Get HTML with specific checkpoint errors highlighted.
+
+**Request Headers:**
+```
+Authorization: Bearer <sessionToken>
+```
+
+**Response (Success - 200):**
+```html
+<html>
+  <!-- HTML with .astHighlightFull, .astError classes for specific checkpoint -->
+</html>
+```
+
+**Backend Implementation:**
+1. Verify session token and retrieve real API key
+2. Call Crownpeak DQM API: `GET https://api.crownpeak.net/dqm-cms/v1/assets/{assetId}/pagehighlight/{checkpointId}?apiKey=<real_api_key>`
+3. Return HTML response to client
+
+---
+
+## Session Management
+
+### Session Token Storage
+
+**Client-Side (localStorage):**
+```javascript
+localStorage.setItem('dqm_sessionToken', 'token');
+localStorage.setItem('dqm_sessionType', 'backend');
+```
+
+**Backend-Side:**
+- Store mapping: `sessionToken -> { apiKey, websiteId, userId, expiresAt }`
+- Recommended: Redis, database, or in-memory cache with TTL
+- Session should expire after inactivity (e.g., 24 hours)
+
+### Token Validation
+
+On every proxied API request:
+1. Extract `Authorization: Bearer <sessionToken>` header
+2. Validate session token (check existence, expiration)
+3. Retrieve associated API key and websiteId
+4. Proxy request to Crownpeak DQM API with real credentials
+
+---
+
+## Error Handling
+
+### Standard Error Response
+
+```json
+{
+  "error": true,
+  "message": "Human-readable error message",
+  "code": "ERROR_CODE" // Optional
+}
+```
+
+### Common HTTP Status Codes
+
+- `200` - Success
+- `400` - Bad Request (invalid input)
+- `401` - Unauthorized (invalid session token or credentials)
+- `403` - Forbidden (valid token but insufficient permissions)
+- `500` - Internal Server Error
+
+---
+
+## Security Considerations
+
+1. **HTTPS Only:** Always use HTTPS in production
+2. **CORS:** Configure CORS to allow requests from your React app domain
+3. **Rate Limiting:** Implement rate limiting on auth endpoints
+4. **Session Expiration:** Sessions should expire after 24 hours or on logout
+5. **Token Rotation:** Consider refreshing session tokens periodically
+6. **CSRF Protection:** Use CSRF tokens for state-changing operations
+7. **Input Validation:** Validate all inputs (API keys, HTML content, etc.)
+8. **API Key Storage:** Store real API keys encrypted in database
+
+---
+
+## Example Backend Implementation (Node.js/Express)
+
+```javascript
+const express = require('express');
+const axios = require('axios');
+const app = express();
+
+// Session store (use Redis in production)
+const sessions = new Map();
+
+// Auth endpoint - Direct credentials
+app.post('/auth/login', async (req, res) => {
+  const { apiKey, websiteId } = req.body;
+  
+  // Validate credentials with Crownpeak API
+  try {
+    const response = await axios.get(
+      `https://api.crownpeak.net/dqm-cms/v1/websites/${websiteId}`,
+      { headers: { 'x-api-key': apiKey } }
+    );
+    
+    // Generate session token
+    const sessionToken = generateUniqueToken();
+    sessions.set(sessionToken, {
+      apiKey,
+      websiteId,
+      expiresAt: Date.now() + 24 * 60 * 60 * 1000, // 24 hours
+    });
+    
+    res.json({ sessionToken, websiteId });
+  } catch (error) {
+    res.status(401).json({ message: 'Invalid credentials' });
+  }
+});
+
+// DQM API Proxy - Start analysis
+app.post('/dqm/assets', authenticateSession, async (req, res) => {
+  const { apiKey, websiteId } = req.session;
+  
+  try {
+    const response = await axios.post(
+      'https://api.crownpeak.net/dqm-cms/v1/assets',
+      req.body,
+      {
+        headers: { 'x-api-key': apiKey },
+        params: { apiKey, websiteId },
+      }
+    );
+    
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ message: 'Analysis failed' });
+  }
+});
+
+// Middleware: Verify session token
+function authenticateSession(req, res, next) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  const session = sessions.get(token);
+  
+  if (!session || session.expiresAt < Date.now()) {
+    return res.status(401).json({ message: 'Invalid or expired session' });
+  }
+  
+  req.session = session;
+  next();
+}
+
+function generateUniqueToken() {
+  return require('crypto').randomBytes(32).toString('hex');
+}
+
+app.listen(3000);
+```
+
+---
+
+## Frontend Configuration
+
+```tsx
+import { DQMSidebar } from '@crownpeak/dqm-react-component';
+
+function App() {
+  return (
+    <DQMSidebar
+      open={true}
+      onOpen={() => {}}
+      onClose={() => {}}
+      config={{
+        authBackendUrl: 'https://your-backend.com', // Backend proxy base URL
+        useLocalStorage: true, // Store session token
+        
+        // Optional: OAuth2 configuration
+        oauth2Config: {
+          authUrl: 'https://oauth-provider.com/authorize',
+          tokenUrl: 'https://oauth-provider.com/token',
+          clientId: 'your_client_id',
+          redirectUri: 'https://your-app.com/oauth-callback',
+          scope: 'dqm:read',
+        },
+      }}
+      onAuthSuccess={(creds) => {
+        console.log('Authenticated:', creds.sessionType); // 'backend'
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Testing
+
+### Test Direct Credentials Flow
+
+```bash
+curl -X POST https://your-backend.com/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"apiKey":"test_key","websiteId":"test_id"}'
+```
+
+### Test Analysis Proxy
+
+```bash
+curl -X POST https://your-backend.com/dqm/assets \
+  -H "Authorization: Bearer <session_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"html":"<html>...</html>","url":"https://example.com"}'
+```
+
+---
+
+## Migration Guide
+
+### From Direct Mode to Backend Mode
+
+1. **Implement backend endpoints** as documented above
+2. **Update React component config:**
+   ```tsx
+   // Before (Direct Mode)
+   config={{
+     apiKey: 'user_api_key',
+     websiteId: 'user_website_id',
+   }}
+   
+   // After (Backend Mode)
+   config={{
+     authBackendUrl: 'https://your-backend.com',
+   }}
+   ```
+3. **Clear old localStorage:**
+   ```javascript
+   localStorage.removeItem('dqm_apiKey');
+   localStorage.removeItem('dqm_websiteID');
+   ```
+
+---
+
+## Support
+
+For questions or issues:
+- Check Crownpeak DQM API docs: https://docs.crownpeak.com/dqm-api
+- Review component source: `src/DQMSidebar.tsx`
+- Check authentication flow: `src/components/auth/`