Initial commit: add .gitignore and README

IDENTITY_MIGRATION_GUIDE.md

@@ -0,0 +1,163 @@
+# Identity System Migration Guide
+
+**Date**: 2025-01-27
+**Purpose**: Guide for migrating projects to unified identity system
+**Status**: Complete
+
+---
+
+## Overview
+
+This guide provides instructions for migrating projects to use the unified identity system (Keycloak).
+
+---
+
+## Prerequisites
+
+- Keycloak deployed and configured
+- Realm created
+- Client configured
+- Users and roles set up
+
+---
+
+## Migration Steps
+
+### Step 1: Install Keycloak Client
+
+```bash
+pnpm add keycloak-js
+```
+
+### Step 2: Configure Keycloak Client
+
+```typescript
+import Keycloak from 'keycloak-js';
+
+const keycloak = new Keycloak({
+  url: process.env.KEYCLOAK_URL || 'http://keycloak:8080',
+  realm: process.env.KEYCLOAK_REALM || 'workspace',
+  clientId: process.env.KEYCLOAK_CLIENT_ID || 'workspace-api',
+});
+```
+
+### Step 3: Initialize Keycloak
+
+```typescript
+async function initKeycloak() {
+  try {
+    const authenticated = await keycloak.init({
+      onLoad: 'login-required',
+      checkLoginIframe: false,
+    });
+
+    if (authenticated) {
+      console.log('User authenticated');
+    }
+  } catch (error) {
+    console.error('Keycloak initialization failed', error);
+  }
+}
+```
+
+### Step 4: Update Authentication
+
+**Before**:
+```typescript
+// Old authentication
+const token = await getTokenFromLocalStorage();
+const response = await fetch('/api/users', {
+  headers: {
+    'Authorization': `Bearer ${token}`,
+  },
+});
+```
+
+**After**:
+```typescript
+// New Keycloak authentication
+const token = keycloak.token;
+const response = await fetch('/api/users', {
+  headers: {
+    'Authorization': `Bearer ${token}`,
+  },
+});
+```
+
+### Step 5: Update Authorization
+
+**Before**:
+```typescript
+// Old role checking
+if (user.roles.includes('admin')) {
+  // Admin action
+}
+```
+
+**After**:
+```typescript
+// New Keycloak role checking
+if (keycloak.hasRealmRole('admin')) {
+  // Admin action
+}
+```
+
+### Step 6: Update Backend
+
+```typescript
+import { verifyToken } from '@workspace/shared-auth';
+
+async function authenticateRequest(req: Request) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (!token) {
+    throw new Error('No token provided');
+  }
+
+  // Verify token with Keycloak
+  const decoded = await verifyToken(token, {
+    issuer: process.env.KEYCLOAK_ISSUER,
+    audience: process.env.KEYCLOAK_CLIENT_ID,
+  });
+
+  return decoded;
+}
+```
+
+---
+
+## Best Practices
+
+### Token Management
+- Use Keycloak token refresh
+- Handle token expiration
+- Store tokens securely
+
+### Role Management
+- Use realm roles for global permissions
+- Use client roles for application-specific permissions
+- Map roles consistently
+
+### User Management
+- Use Keycloak user federation
+- Sync users from external systems
+- Manage users centrally
+
+---
+
+## Migration Checklist
+
+- [ ] Install Keycloak client
+- [ ] Configure Keycloak connection
+- [ ] Update authentication code
+- [ ] Update authorization code
+- [ ] Update backend verification
+- [ ] Test authentication
+- [ ] Test authorization
+- [ ] Update documentation
+- [ ] Migrate users
+- [ ] Set up user federation (if needed)
+
+---
+
+**Last Updated**: 2025-01-27
+